Getting Started

What is APX Design System?

APX DS is a production-ready React component library built for modern applications. It's designed with three core principles:

Themable — Switch between light/dark modes, apply visual variants (default, tetsu, origami, katana), and override any token or component style without forking
RTL-Ready — Full bidirectional support using CSS logical properties — flip between LTR and RTL with a single attribute change
Fully Overridable — A strict 5-layer styling precedence lets you customize everything from design tokens down to individual component instances

Packages

The design system ships as two separate npm packages:

Package	Description	Bundle Impact
`@apx-ui/ds`	Core library — 60+ components, theme engine, Tailwind preset	Required
`@apx-ui/icons`	SVG icon set — tree-shakable, only ships what you import	Optional

Installation

Core Library (Required)

bash

npm install @apx-ui/ds
# or
pnpm add @apx-ui/ds

npm install @apx-ui/ds
# or
pnpm add @apx-ui/ds

Icons Library (Optional)

bash

npm install @apx-ui/icons
# or
pnpm add @apx-ui/icons

npm install @apx-ui/icons
# or
pnpm add @apx-ui/icons

Setup

Step 1: Configure the Root Provider

Wrap your application with <ThemeProvider> and inject <ThemeScript /> in the document head. The script runs before React hydrates, preventing any flash of unstyled content:

tsx

import { ThemeProvider, ThemeScript } from '@apx-ui/ds';
import '@apx-ui/ds/styles/reset.css';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <ThemeScript />
      </head>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}

import { ThemeProvider, ThemeScript } from '@apx-ui/ds';
import '@apx-ui/ds/styles/reset.css';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <ThemeScript />
      </head>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}

The provider manages three orthogonal axes that propagate via CSS variables:

Axis	Values	Default
Mode	`light`, `dark`, `system`	`system`
Variant	`default`, `tetsu`, `origami`, `katana`	`default`
Direction	`ltr`, `rtl`	`ltr`

Step 2: Configure Tailwind

Add the APX Tailwind preset to your config. This maps all design tokens to Tailwind theme keys:

import { apxTailwindPreset } from '@apx-ui/ds/tailwind-preset';

export default {
  presets: [apxTailwindPreset],
  content: ['./src/**/*.{ts,tsx,mdx}'],
};

import { apxTailwindPreset } from '@apx-ui/ds/tailwind-preset';

export default {
  presets: [apxTailwindPreset],
  content: ['./src/**/*.{ts,tsx,mdx}'],
};

Now utility classes like bg-primary, text-fg, border-border, rounded-md resolve through DS CSS variables — they automatically respond to mode, variant, and direction changes without any JavaScript re-renders.

Usage

Components

Import and use components directly. Every component supports consistent props for variant, size, color, and full style overrides:

tsx

import { Button, Input, Card, Badge } from '@apx-ui/ds';

export default function UserCard() {
  return (
    <Card variant="elevated" size="md">
      <Card.Header>
        <Card.Header.Title>Welcome Back</Card.Header.Title>
        <Badge color="success">Online</Badge>
      </Card.Header>
      <Card.Body>
        <Input placeholder="Search your projects..." />
        <Button color="primary" size="lg">
          Get Started
        </Button>
      </Card.Body>
    </Card>
  );
}

import { Button, Input, Card, Badge } from '@apx-ui/ds';

export default function UserCard() {
  return (
    <Card variant="elevated" size="md">
      <Card.Header>
        <Card.Header.Title>Welcome Back</Card.Header.Title>
        <Badge color="success">Online</Badge>
      </Card.Header>
      <Card.Body>
        <Input placeholder="Search your projects..." />
        <Button color="primary" size="lg">
          Get Started
        </Button>
      </Card.Body>
    </Card>
  );
}

Icons

Icons are standalone React components with consistent sizing and color inheritance:

tsx

import { Search, Check, ChevronRight } from '@apx-ui/icons';
import { Input, Button } from '@apx-ui/ds';

export default function SearchField() {
  return (
    <div className="flex items-center gap-2">
      <Search className="text-fg-muted" size={18} />
      <Input placeholder="Search..." className="flex-1" />
      <Button color="primary">
        Go <ChevronRight size={16} />
      </Button>
    </div>
  );
}

import { Search, Check, ChevronRight } from '@apx-ui/icons';
import { Input, Button } from '@apx-ui/ds';

export default function SearchField() {
  return (
    <div className="flex items-center gap-2">
      <Search className="text-fg-muted" size={18} />
      <Input placeholder="Search..." className="flex-1" />
      <Button color="primary">
        Go <ChevronRight size={16} />
      </Button>
    </div>
  );
}

Browse all available icons in the Icons Gallery.

Theme Engine & Customization

The theme engine gives you complete control over the visual layer without touching component internals. You can:

Switch modes — Toggle light/dark/system with useMode() hook
Apply variants — Swap entire visual families (radii, shadows, spacing) at once
Override tokens — Customize colors, typography, motion at the design-token level
Override components — Target specific components with styleOverrides in your theme
Override instances — Use className, sx, or style props on individual elements

tsx

import { ThemeProvider, defineTheme } from '@apx-ui/ds';

const customTheme = defineTheme({
  variants: {
    brand: {
      radius: { md: '12px', lg: '16px' },
      colors: {
        primary: { 500: '#6366f1' },
      },
    },
  },
});

export default function App({ children }) {
  return (
    <ThemeProvider theme={customTheme} defaultVariant="brand">
      {children}
    </ThemeProvider>
  );
}

import { ThemeProvider, defineTheme } from '@apx-ui/ds';

const customTheme = defineTheme({
  variants: {
    brand: {
      radius: { md: '12px', lg: '16px' },
      colors: {
        primary: { 500: '#6366f1' },
      },
    },
  },
});

export default function App({ children }) {
  return (
    <ThemeProvider theme={customTheme} defaultVariant="brand">
      {children}
    </ThemeProvider>
  );
}

What's Next?

Components
Explore the full catalog — from basic inputs to complex data grids, calendars, and schedulers.

Icons
Browse the icon gallery with search, copy-to-clipboard, and live previews.

Theming
Master the theme engine — modes, variants, tokens, and the override precedence system.

Getting Started

What is APX Design System?

APX DS is a production-ready React component library built for modern applications. It's designed with three core principles:

Themable — Switch between light/dark modes, apply visual variants (default, tetsu, origami, katana), and override any token or component style without forking
RTL-Ready — Full bidirectional support using CSS logical properties — flip between LTR and RTL with a single attribute change
Fully Overridable — A strict 5-layer styling precedence lets you customize everything from design tokens down to individual component instances

Packages

The design system ships as two separate npm packages:

Package	Description	Bundle Impact
`@apx-ui/ds`	Core library — 60+ components, theme engine, Tailwind preset	Required
`@apx-ui/icons`	SVG icon set — tree-shakable, only ships what you import	Optional

Installation

Core Library (Required)

bash

npm install @apx-ui/ds
# or
pnpm add @apx-ui/ds

npm install @apx-ui/ds
# or
pnpm add @apx-ui/ds

Icons Library (Optional)

bash

npm install @apx-ui/icons
# or
pnpm add @apx-ui/icons

npm install @apx-ui/icons
# or
pnpm add @apx-ui/icons

Setup

Step 1: Configure the Root Provider

Wrap your application with <ThemeProvider> and inject <ThemeScript /> in the document head. The script runs before React hydrates, preventing any flash of unstyled content:

tsx

import { ThemeProvider, ThemeScript } from '@apx-ui/ds';
import '@apx-ui/ds/styles/reset.css';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <ThemeScript />
      </head>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}

import { ThemeProvider, ThemeScript } from '@apx-ui/ds';
import '@apx-ui/ds/styles/reset.css';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <ThemeScript />
      </head>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}

The provider manages three orthogonal axes that propagate via CSS variables:

Axis	Values	Default
Mode	`light`, `dark`, `system`	`system`
Variant	`default`, `tetsu`, `origami`, `katana`	`default`
Direction	`ltr`, `rtl`	`ltr`

Step 2: Configure Tailwind

Add the APX Tailwind preset to your config. This maps all design tokens to Tailwind theme keys:

import { apxTailwindPreset } from '@apx-ui/ds/tailwind-preset';

export default {
  presets: [apxTailwindPreset],
  content: ['./src/**/*.{ts,tsx,mdx}'],
};

import { apxTailwindPreset } from '@apx-ui/ds/tailwind-preset';

export default {
  presets: [apxTailwindPreset],
  content: ['./src/**/*.{ts,tsx,mdx}'],
};

Usage

Components

Import and use components directly. Every component supports consistent props for variant, size, color, and full style overrides:

tsx

import { Button, Input, Card, Badge } from '@apx-ui/ds';

export default function UserCard() {
  return (
    <Card variant="elevated" size="md">
      <Card.Header>
        <Card.Header.Title>Welcome Back</Card.Header.Title>
        <Badge color="success">Online</Badge>
      </Card.Header>
      <Card.Body>
        <Input placeholder="Search your projects..." />
        <Button color="primary" size="lg">
          Get Started
        </Button>
      </Card.Body>
    </Card>
  );
}

import { Button, Input, Card, Badge } from '@apx-ui/ds';

export default function UserCard() {
  return (
    <Card variant="elevated" size="md">
      <Card.Header>
        <Card.Header.Title>Welcome Back</Card.Header.Title>
        <Badge color="success">Online</Badge>
      </Card.Header>
      <Card.Body>
        <Input placeholder="Search your projects..." />
        <Button color="primary" size="lg">
          Get Started
        </Button>
      </Card.Body>
    </Card>
  );
}

Icons

Icons are standalone React components with consistent sizing and color inheritance:

tsx

import { Search, Check, ChevronRight } from '@apx-ui/icons';
import { Input, Button } from '@apx-ui/ds';

export default function SearchField() {
  return (
    <div className="flex items-center gap-2">
      <Search className="text-fg-muted" size={18} />
      <Input placeholder="Search..." className="flex-1" />
      <Button color="primary">
        Go <ChevronRight size={16} />
      </Button>
    </div>
  );
}

import { Search, Check, ChevronRight } from '@apx-ui/icons';
import { Input, Button } from '@apx-ui/ds';

export default function SearchField() {
  return (
    <div className="flex items-center gap-2">
      <Search className="text-fg-muted" size={18} />
      <Input placeholder="Search..." className="flex-1" />
      <Button color="primary">
        Go <ChevronRight size={16} />
      </Button>
    </div>
  );
}

Browse all available icons in the Icons Gallery.

Theme Engine & Customization

The theme engine gives you complete control over the visual layer without touching component internals. You can:

Switch modes — Toggle light/dark/system with useMode() hook
Apply variants — Swap entire visual families (radii, shadows, spacing) at once
Override tokens — Customize colors, typography, motion at the design-token level
Override components — Target specific components with styleOverrides in your theme
Override instances — Use className, sx, or style props on individual elements

tsx

import { ThemeProvider, defineTheme } from '@apx-ui/ds';

const customTheme = defineTheme({
  variants: {
    brand: {
      radius: { md: '12px', lg: '16px' },
      colors: {
        primary: { 500: '#6366f1' },
      },
    },
  },
});

export default function App({ children }) {
  return (
    <ThemeProvider theme={customTheme} defaultVariant="brand">
      {children}
    </ThemeProvider>
  );
}

import { ThemeProvider, defineTheme } from '@apx-ui/ds';

const customTheme = defineTheme({
  variants: {
    brand: {
      radius: { md: '12px', lg: '16px' },
      colors: {
        primary: { 500: '#6366f1' },
      },
    },
  },
});

export default function App({ children }) {
  return (
    <ThemeProvider theme={customTheme} defaultVariant="brand">
      {children}
    </ThemeProvider>
  );
}

What's Next?

Components
Explore the full catalog — from basic inputs to complex data grids, calendars, and schedulers.

Icons
Browse the icon gallery with search, copy-to-clipboard, and live previews.

Theming
Master the theme engine — modes, variants, tokens, and the override precedence system.