Aras React Components

A React component library built on Carbon Design System v11 with Aras branding and styling. This library provides a comprehensive set of components, utilities, and a custom Aras theme.

📚 Documentation

• Our StoryBook here
• Check the docs folder!

Installation

npm install @arascorp/react-components

Peer Dependencies

This library requires the following peer dependencies:

npm install react react-dom @carbon/react @carbon/icons-react

Quick Start

1. Import Styles

Import the compiled CSS in your main entry file:

// src/main.tsx or src/index.tsx
import "@arascorp/react-components/styles";

2. Apply Theme

Wrap your application with the Theme component:

import { Theme } from "@arascorp/react-components";
import ReactDOM from "react-dom/client";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <Theme>
    <App />
  </Theme>
);

3. Use Components

import { Button, TextInput } from "@arascorp/react-components";

function MyComponent() {
  return (
    <>
      <Button kind="primary">Click me</Button>
      <TextInput labelText="Name" placeholder="Enter your name" />
    </>
  );
}

Theming

Aras Theme (Recommended)

The library includes a custom Aras theme with brand colors, which is applied by default:

import { Theme } from "@arascorp/react-components";

function App() {
  return <Theme>{/* Your app content - uses aras-theme by default */}</Theme>;
}

Aras Brand Colors:

• Primary: #61a5f3 (Aras Blue)
• Hover: #4496d4
• Active: #1f70c1

Carbon Themes

You can also use standard Carbon themes:

import { Theme } from "@arascorp/react-components";

function App() {
  const [theme, setTheme] = useState("white");

  return <Theme theme={theme}>{/* Your app content */}</Theme>;
}

Available themes:

• aras-theme - Custom Aras theme (default)
• white - Clean white background
• g10 - Light gray background
• g90 - Dark theme
• g100 - Darkest theme

📖 ** See full theming guide in docs**

Utility Classes

The library includes comprehensive utility classes for common styling needs. All utility classes use the aras- prefix to avoid conflicts with other libraries:

// Spacing
<div className="aras-p-4 aras-mb-6">Padding and margin</div>

// Layout - Grid
<div className="aras-grid aras-grid-cols-3 aras-gap-4">
  <div className="aras-bg-layer-01 aras-p-4">Item 1</div>
  <div className="aras-bg-layer-01 aras-p-4">Item 2</div>
  <div className="aras-bg-layer-01 aras-p-4">Item 3</div>
</div>

// Flexbox
<div className="aras-flex aras-items-center aras-justify-between aras-gap-4">
  <span>Left</span>
  <span>Right</span>
</div>

// Typography
<h1 className="aras-text-2xl aras-font-bold aras-text-primary">Heading</h1>

// Colors
<div className="aras-bg-layer-01 aras-text-secondary">Content</div>

📖 See full utilities guide in docs folder

Components

The library provides Aras-branded versions of Carbon components with consistent styling and additional features.

Core Components

Button

Button component with Aras styling and multiple variants:

import { Button } from "@arascorp/react-components";

function MyComponent() {
  return (
    <>
      <Button kind="primary">Primary</Button>
      <Button kind="secondary">Secondary</Button>
      <Button kind="tertiary">Tertiary</Button>
      <Button kind="ghost">Ghost</Button>
      <Button kind="danger">Danger</Button>
    </>
  );
}

Sizes:

<Button size="sm">Small</Button>
<Button size="md">Medium (default)</Button>
<Button size="lg">Large</Button>
<Button size="xl">Extra Large</Button>

Form Components

import {
  TextInput,
  TextArea,
  Select,
  SelectItem,
  Checkbox,
  RadioButton,
  Toggle,
  DatePicker,
  TimePicker
} from '@arascorp/react-components';

// Text Input
<TextInput
  labelText="Email"
  placeholder="Enter your email"
  type="email"
/>

// Select
<Select
  labelText="Choose option"
  id="select-1"
>
  <SelectItem value="option1" text="Option 1" />
  <SelectItem value="option2" text="Option 2" />
</Select>

// Checkbox
<Checkbox
  labelText="Accept terms"
  id="checkbox-1"
/>

Layout Components

import {
  Stack,
  Grid,
  Section,
  FluidForm
} from '@arascorp/react-components';

// Stack for vertical layouts
<Stack gap={4}>
  <div>Item 1</div>
  <div>Item 2</div>
</Stack>

// Grid layout (re-exported from Carbon)
<Grid>
  <Row>
    <Column>Content</Column>
  </Row>
</Grid>

// Fluid Form
<FluidForm>
  <FluidTextInput labelText="Name" />
  <FluidTextInput labelText="Email" />
</FluidForm>

Data Display

import { DataTable, StructuredList, Tile, Accordion } from "@arascorp/react-components";

// Tiles
<Tile>
  <h3>Tile Title</h3>
  <p>Tile content</p>
</Tile>;

Notifications

import {
  InlineNotification,
  ToastNotification,
  Callout
} from '@arascorp/react-components';

<InlineNotification
  kind="success"
  title="Success"
  subtitle="Operation completed successfully"
/>

<Callout kind="info" title="Information">
  This is an informational callout
</Callout>

All Available Components

import {
  // Buttons
  Button,
  IconButton,
  ComboButton,
  CopyButton,
  OverflowMenu,

  // Forms
  TextInput,
  TextArea,
  NumberInput,
  Select,
  ComboBox,
  Dropdown,
  MultiSelect,
  Checkbox,
  RadioButton,
  Toggle,
  Switch,
  Slider,
  DatePicker,
  TimePicker,
  FileUploader,
  Search,

  // Layout
  Stack,
  Grid,
  Section,
  FluidForm,
  Breadcrumb,
  Tabs,
  Accordion,

  // Data Display
  DataTable,
  StructuredList,
  Tile,
  Tag,
  CodeSnippet,

  // Feedback
  InlineNotification,
  Modal,
  Tooltip,
  Toggletip,
  Popover,
  Loading,
  InlineLoading,
  ProgressIndicator,
  Callout,

  // Navigation
  Menu,
  MenuButton,
  Link,
  Pagination,
  PaginationNav,

  // Other
  Heading,
  Theme,
  GlobalTheme
} from "@arascorp/react-components";

Exported Modules

Styles Export

// Import all styles (includes Carbon + Aras theme)
import "@arascorp/react-components/styles";

The styles export includes:

• All Carbon Design System styles
• Aras custom theme with brand colors
• Utility classes for spacing, typography, etc.
• CSS custom properties for theming

Component Re-exports

Commonly used Carbon React components are re-exported for convenience:

// Both Aras and Carbon components from same package
import {
  Button, // Aras component
  Grid, // Carbon component
  Row, // Carbon component
  Column // Carbon component
} from "@arascorp/react-components";

Development

Building the Library

Build both JavaScript and CSS:

npm run build

This runs:

1. build:js - Compiles TypeScript/React components with Vite
2. build:styles - Compiles SCSS to CSS

Running Storybook

View all components in Storybook:

npm run storybook

Then open http://localhost:6006

Type Checking

npm run type-check

Linting

npm run lint

Project Structure

src/
├── components/        # Aras component wrappers
├── scss/             # Theme and styles
│   ├── aras-theme.scss
│   └── utilities/
├── utilities/        # Utility class generators
│   ├── Spacing/
│   ├── Typography/
│   ├── Colors/
│   └── ...
├── stories/          # Storybook stories
└── index.ts          # Main export file

index.scss            # Main SCSS entry point

Advanced Usage

Custom Theme Tokens

Access Aras theme tokens in your CSS:

.my-component {
  background: var(--cds-button-primary);
  color: var(--cds-text-on-color);
  border: 1px solid var(--cds-border-subtle);
}

Using SCSS Variables

Import theme variables in your SCSS files:

@use "sass:map";
@use "@arascorp/react-components/src/scss/aras-theme" as aras;

.my-component {
  background: map.get(aras.$aras-palette, "blue-60");
}

Available variables:

• $aras-palette - Complete color palette with Aras brand colors
• $aras-theme - Theme configuration map
• $aras-color-overrides - Aras-specific color overrides

Extending Components

Create custom components based on Aras components:

import { Button } from "@arascorp/react-components";

function MyCustomButton({ children, ...props }) {
  return (
    <Button {...props} className="my-custom-button">
      {children}
    </Button>
  );
}

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Accessibility

All components follow Carbon Design System accessibility guidelines:

• WCAG 2.1 AA compliant
• Keyboard navigation support
• Screen reader optimized
• Focus management
• ARIA attributes

Performance

• Tree-shakeable ES modules
• Optimized CSS with utility purging
• Lazy loading support
• Production-ready builds
• Source maps for debugging

Troubleshooting

Styles Not Loading / Layout Broken

Problem: Components render but styles aren't applied, layouts are broken, grid doesn't work.

Solution: Make sure you've imported the styles in your main entry file:

// src/main.tsx or src/index.tsx - ADD THIS AT THE TOP
import "@arascorp/react-components/styles";

import { Theme } from "@arascorp/react-components";
import ReactDOM from "react-dom/client";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <Theme>
    <App />
  </Theme>
);

Utility Classes Not Working

Problem: Using utility classes like className="grid grid-cols-3 gap-4" but layout is broken.

Solution: All utility classes require the aras- prefix. Update your code:

// ❌ WRONG - Missing aras- prefix
<div className="grid grid-cols-3 gap-4">
  <div className="bg-layer-01 p-4">Item 1</div>
  <div className="bg-layer-01 p-4">Item 2</div>
  <div className="bg-layer-01 p-4">Item 3</div>
</div>

// ✅ CORRECT - With aras- prefix
<div className="aras-grid aras-grid-cols-3 aras-gap-4">
  <div className="aras-bg-layer-01 aras-p-4">Item 1</div>
  <div className="aras-bg-layer-01 aras-p-4">Item 2</div>
  <div className="aras-bg-layer-01 aras-p-4">Item 3</div>
</div>

Common utility class fixes:

• grid → aras-grid
• flex → aras-flex
• p-4, m-4 → aras-p-4, aras-m-4
• gap-4 → aras-gap-4
• bg-layer-01 → aras-bg-layer-01
• text-primary → aras-text-primary

See the full Utilities Guide for all available classes.

TypeScript Cannot Find Module "@arascorp/react-components/styles"

Problem: TypeScript error when importing styles.

Solution: Update to version 0.1.12-beta.37784 or higher:

npm install @arascorp/react-components@latest

Theme Not Applying

Make sure your components are wrapped in a theme provider:

<Theme>
  <YourComponents />
</Theme>

TypeScript Errors

Ensure you have the correct TypeScript version (^5.0.0) and that types are being resolved correctly in your tsconfig.json.

Migration Guide

From Carbon v10 to Aras Components

Old:

import { Button } from "@carbon/react";
import "@carbon/styles/css/styles.css";

<Button kind="primary">Click</Button>;

New:

import { Button } from "@arascorp/react-components";
import "@arascorp/react-components/styles";

<Theme>
  <Button kind="primary">Click</Button>
</Theme>;

Examples

Complete Application Setup

// main.tsx
import ReactDOM from "react-dom/client";
import "@arascorp/react-components/styles";
import { Theme } from "@arascorp/react-components";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <Theme>
    <App />
  </Theme>
);

// App.tsx
import { Button, TextInput, Stack } from "@arascorp/react-components";

export default function App() {
  return (
    <div className="p-6">
      <Stack gap={4}>
        <h1 className="text-3xl font-bold">Welcome to Aras</h1>
        <TextInput labelText="Email" placeholder="Enter your email" />
        <Button kind="primary">Get Started</Button>
      </Stack>
    </div>
  );
}

Form Example

import { FluidForm, FluidTextInput, FluidSelect, SelectItem, Button, Stack } from "@arascorp/react-components";

function ContactForm() {
  return (
    <FluidForm>
      <Stack gap={4}>
        <FluidTextInput labelText="Full Name" placeholder="John Doe" />
        <FluidTextInput labelText="Email" type="email" placeholder="[email protected]" />
        <FluidSelect labelText="Department">
          <SelectItem value="sales" text="Sales" />
          <SelectItem value="support" text="Support" />
          <SelectItem value="engineering" text="Engineering" />
        </FluidSelect>
        <Button kind="primary" type="submit">
          Submit
        </Button>
      </Stack>
    </FluidForm>
  );
}

Development Guidelines

• Follow existing code style and patterns
• Add Storybook stories for new components
• Update documentation for API changes
• Ensure TypeScript types are complete
• Test with multiple themes (white, g90, aras-theme)

Resources

• Storybook Documentation
• Carbon Design System
• Carbon React Components
• Check the docs folder for more!

License

MIT © Aras Corporation

Made with ❤️ by the Aras Engineering Team