@shadowfax-tech/sfx-cargo-ui# @shadowfax-tech/sfx-cargo-ui# @shadowfax-tech/sfx-cargo-ui

A comprehensive design system and UI component library for Shadowfax applications. Supports both modern CSS Modules and traditional Vanilla SCSS approaches for maximum flexibility.

🚀 InstallationA comprehensive design system and UI component library for Shadowfax applications. Supports both modern CSS Modules and traditional Vanilla SCSS approaches for maximum flexibility.A design system and UI component library for Shadowfax applications.

npm install @shadowfax-tech/sfx-cargo-ui

```## 🚀 Installation## 🚀 Installation



or



```bash```bash```bash

yarn add @shadowfax-tech/sfx-cargo-ui

```npm install @shadowfax-tech/sfx-cargo-uinpm install @shadowfax-tech/sfx-cargo-ui



## 📖 Styling Approaches``````



This library offers two distinct styling approaches. Choose based on your project needs:



### 1️⃣ CSS Modules (Recommended for Modern Apps) ⭐or```bash



**Best for:** Component libraries, modern SPAs, React/Vue/Angular apps with build tools, TypeScript projects.yarn add @shadowfax-tech/sfx-cargo-ui



**Benefits:** Type-safe, scoped styles, tree-shakeable, zero style conflicts, smaller bundle size.```bash```



#### Quick Startyarn add @shadowfax-tech/sfx-cargo-ui

```tsx

import colors from '@shadowfax-tech/sfx-cargo-ui/styles/css-modules/colors.module.scss';```## 📖 Usage

import spacing from '@shadowfax-tech/sfx-cargo-ui/styles/css-modules/spacing.module.scss';

import typography from '@shadowfax-tech/sfx-cargo-ui/styles/css-modules/typography.module.scss';

import utils from '@shadowfax-tech/sfx-cargo-ui/styles/css-modules/utils.module.scss';

## 📖 Styling Approaches### Modern Approach: SCSS Modules (Recommended)

function Card() {

  return (

    <div className={`${colors.bgPrimary} ${spacing.pMd} ${utils.roundedLg}`}>

      <h1 className={typography.h1}>Card Title</h1>This library offers two distinct styling approaches. Choose based on your project needs:The design system supports SCSS modules for type-safe, scoped styling in modern applications:

      <p className={`${typography.body} ${colors.textSecondary}`}>

        This uses CSS modules for scoped styling

      </p>

    </div>### 1️⃣ CSS Modules (Recommended for Modern Apps) ⭐#### Option 1: CSS Modules with Utility Classes

  );

}```tsx

Best for: Component libraries, modern SPAs, React/Vue/Angular apps with build tools, TypeScript projects.// React/Vue/Angular - Import utility classes as modules

Available CSS Modules

import colors from '@shadowfax-tech/sfx-ui-theme/styles/modules/colors.module.scss';

• colors.module.scss - Background, text, border color classes

• spacing.module.scss - Padding, margin, gap utility classesBenefits: Type-safe, scoped styles, tree-shakeable, zero style conflicts, smaller bundle size.import spacing from '@shadowfax-tech/sfx-ui-theme/styles/modules/spacing.module.scss';

• typography.module.scss - Font sizes, weights, heading styles

• utils.module.scss - Border radius, shadows, z-index utilitiesimport typography from '@shadowfax-tech/sfx-ui-theme/styles/modules/typography.module.scss';

• tokens.module.scss - CSS custom properties (:root variables)

Quick Startimport utils from '@shadowfax-tech/sfx-ui-theme/styles/modules/utils.module.scss';

Using CSS Custom Properties

Import tokens at your app root and use CSS variables throughout your code:

import colors from '@shadowfax-tech/sfx-cargo-ui/styles/css-modules/colors.module.scss';function MyComponent() {

```tsx

// App.tsximport spacing from '@shadowfax-tech/sfx-cargo-ui/styles/css-modules/spacing.module.scss';  return (

import tokens from '@shadowfax-tech/sfx-cargo-ui/styles/css-modules/tokens.module.scss';

import typography from '@shadowfax-tech/sfx-cargo-ui/styles/css-modules/typography.module.scss';    <div className={`${colors.bgPrimary} ${spacing.pMd} ${utils.roundedLg}`}>

function App() {

  return <div className={tokens.container}>{/* app content */}</div>;import utils from '@shadowfax-tech/sfx-cargo-ui/styles/css-modules/utils.module.scss';      <h1 className={typography.h1}>Welcome</h1>

}

```      <p className={`${typography.body} ${colors.textSecondary}`}>



```scssfunction Card() {        Styled with CSS modules

// any.component.scss

.button {  return (      </p>

  background: var(--sfx-bg-primary);

  color: var(--sfx-text-primary);    <div className={`${colors.bgPrimary} ${spacing.pMd} ${utils.roundedLg}`}>    </div>

  padding: var(--sfx-spacing-sm) var(--sfx-spacing-md);

  border-radius: var(--sfx-radius-base);      <h1 className={typography.h1}>Card Title</h1>  );

  box-shadow: var(--sfx-shadow-sm);

}      <p className={`${typography.body} ${colors.textSecondary}`}>}

    This uses CSS modules for scoped styling```

2️⃣ Vanilla SCSS (Traditional Approach)

  </p>

Best for: Multi-page applications, server-rendered projects, when you need powerful SCSS features, legacy projects.

</div>#### Option 2: CSS Custom Properties (Variables)

Benefits: Direct SCSS variables, mixins, functions, single global import, familiar syntax.

);```tsx

Quick Start

}// Import tokens at root level

// styles.scss```import tokens from '@shadowfax-tech/sfx-ui-theme/styles/tokens.module.scss';

@import '@shadowfax-tech/sfx-cargo-ui/styles/vanilla/complete';



.button {

  @include sfx-padding(sm);#### Available CSS Modulesfunction App() {

  @include sfx-radius(base);

  background: $sfx-primary-500;  return <div className={tokens.container}>{/* Your app */}</div>;

}

```- **`colors.module.scss`** - Background, text, border color classes}



#### Using @use Syntax- **`spacing.module.scss`** - Padding, margin, gap utility classes```



```scss- **`typography.module.scss`** - Font sizes, weights, heading styles

@use '@shadowfax-tech/sfx-cargo-ui/styles' as sfx;

- **`utils.module.scss`** - Border radius, shadows, z-index utilities```scss

.component {

  @include sfx.sfx-typography(h3);- **`tokens.module.scss`** - CSS custom properties (:root variables)// Use CSS variables anywhere in your stylesheets

  @include sfx.sfx-padding(lg);

  @include sfx.sfx-radius(md);.my-component {

  background: sfx.$sfx-bg-primary;

  color: sfx.$sfx-text-primary;#### Using CSS Custom Properties  background-color: var(--sfx-bg-primary);

}

```  padding: var(--sfx-spacing-md);



### 🎯 Choosing Your ApproachImport tokens at your app root and use CSS variables throughout your code:  border-radius: var(--sfx-radius-lg);



| Feature | CSS Modules | Vanilla SCSS |  color: var(--sfx-text-primary);

|---------|-------------|--------------|

| **Type Safety** | ✅ Full TypeScript | ⚠️ Via types file |```tsx  font-size: var(--sfx-font-size-base);

| **Scoped Styles** | ✅ By default | ❌ Global |

| **Bundle Size** | ✅ Smaller | ⚠️ Full file |// App.tsx  box-shadow: var(--sfx-shadow-md);

| **Tree Shaking** | ✅ Yes | ❌ No |

| **CSS Variables** | ✅ Full support | ✅ Full support |import tokens from '@shadowfax-tech/sfx-cargo-ui/styles/css-modules/tokens.module.scss';}

| **SCSS Mixins** | ❌ No | ✅ Yes |

| **Framework Support** | ✅ Universal | ✅ Universal |```



**🎯 Recommendation:** Use CSS Modules for new projects. Use Vanilla SCSS for legacy projects or when you need advanced SCSS features.function App() {



## 📁 Directory Structure  return <div className={tokens.container}>{/* app content */}</div>;#### Option 3: SCSS Mixins (Advanced)



```}```scss

src/lib/styles/

├── css-modules/                  # CSS Modules (Recommended)```@use '@shadowfax-tech/sfx-ui-theme/styles' as sfx;

│   ├── tokens.module.scss        # CSS custom properties

│   ├── colors.module.scss        # Color utilities

│   ├── spacing.module.scss       # Spacing utilities

│   ├── typography.module.scss    # Typography utilities```scss.my-component {

│   ├── utils.module.scss         # Utility classes

│   └── index.d.ts                # TypeScript declarations// any.component.scss  @include sfx.sfx-typography(body);

│

├── vanilla/                      # Vanilla SCSS (Traditional).button {  @include sfx.sfx-padding(md);

│   ├── complete.scss             # Everything in one import

│   ├── index.scss                # Core design system  background: var(--sfx-bg-primary);  @include sfx.sfx-radius(lg);

│   ├── mixins.scss               # SCSS mixins

│   ├── base/                     # Base styles  color: var(--sfx-text-primary);  background-color: sfx.$sfx-bg-primary;

│   ├── foundations/              # Design tokens

│   └── themes/                   # Theme definitions  padding: var(--sfx-spacing-sm) var(--sfx-spacing-md);}

│

├── fonts.scss                    # Font imports (shared)  border-radius: var(--sfx-radius-base);```

├── icons/                        # Icon configuration

└── plugins/                      # Custom plugins  box-shadow: var(--sfx-shadow-sm);

}### Traditional Approach: Global SCSS Imports

🎨 Design Tokens

### Color Tokens

- Primary: `$sfx-primary-50` to `$sfx-primary-900`For projects that prefer traditional global styles:

- Neutral: `$sfx-neutral-50` to `$sfx-neutral-900`

- Semantic: `$sfx-bg-primary`, `$sfx-text-primary`, `$sfx-border-primary`### 2️⃣ Vanilla SCSS (Traditional Approach)

- Status: `$sfx-success-color`, `$sfx-error-color`, `$sfx-warning-color`

#### Complete Design System

### Spacing Scale

- Base unit: 4px**Best for:** Multi-page applications, server-rendered projects, when you need powerful SCSS features, legacy projects.```scss

- Semantic: `xs` (4px), `sm` (8px), `md` (16px), `lg` (24px), `xl` (32px), `2xl` (48px), `3xl` (64px)

// Imports everything: fonts, themes, typography, colors, shadows, mixins

### Border Radius

- Values: `none`, `sm`, `base`, `md`, `lg`, `xl`, `2xl`, `3xl`, `full`**Benefits:** Direct SCSS variables, mixins, functions, single global import, familiar syntax.@import '@shadowfax-tech/sfx-ui-theme/styles/complete';



### Typography```

- Font family: Inter with system fallbacks

- Sizes: Responsive scale from `xs` to `6xl`#### Quick Start

- Weights: Thin (100) to Black (900)

- Line heights: Paired with each size#### Core Design System



### Shadows```scss```scss

- Scale: `none`, `xs` through `2xl`

- Soft, hard, and glass morphism effects// styles.scss// Imports main design system (fonts, themes, foundations, mixins)



## 🧩 Icon Components@import '@shadowfax-tech/sfx-cargo-ui/styles/vanilla/complete';@import '@shadowfax-tech/sfx-ui-theme/styles';



380+ pre-built icons in multiple formats:```



**React:**.button {

```tsx

import { RocketLaunch, Star } from '@shadowfax-tech/sfx-cargo-ui/icons/react';  @include sfx-padding(sm);#### Selective Imports

<RocketLaunch size={24} color="#3b82f6" />

```  @include sfx-radius(base);```scss



**Angular:**  background: $sfx-primary-500;// Import only what you need

```html

<sfx-rocket-launch [size]="24" color="#3b82f6"></sfx-rocket-launch>}@import '@shadowfax-tech/sfx-ui-theme/fonts';

**See [Icon Documentation](./src/icons/README.md) for complete guide.**

@import '@shadowfax-tech/sfx-ui-theme/styles/base';

## 🛠️ Development

#### Using @use Syntax```

### Available Scripts



```bash

yarn dev                   # Start Vite dev server```scss> 💡 **Tip**: Use CSS Modules for component libraries and modern applications. Use global imports for traditional multi-page applications.

yarn storybook             # Start Storybook

yarn build                 # Build library@use '@shadowfax-tech/sfx-cargo-ui/styles' as sfx;

yarn build:lib             # Build dist

yarn build-storybook       # Build Storybook for production### Using in JavaScript/TypeScript

yarn generate-icons        # Generate icons from SVG

```.component {



### Building  @include sfx.sfx-typography(h3);```typescript



```bash  @include sfx.sfx-padding(lg);import { StyleUtils } from '@shadowfax/sfx-cargo-ui';

yarn build:lib

```  @include sfx.sfx-radius(md);import type { Theme, ColorTokens } from '@shadowfax/sfx-cargo-ui';



### Publishing  background: sfx.$sfx-bg-primary;```



```bash  color: sfx.$sfx-text-primary;

npm run prepublishOnly

npm publish}## 🛠️ Development

## 📚 Documentation

### Building the Library

- **README.md** (this file) - Quick start and reference

- **src/lib/styles/css-modules/** - CSS Modules detailed guide### 🎯 Choosing Your Approach

- **src/lib/styles/vanilla/** - Vanilla SCSS detailed guide

- **src/icons/README.md** - Icon documentation```bash

- **Storybook** - Interactive explorer (`yarn storybook`)

| Feature | CSS Modules | Vanilla SCSS |npm run build:lib

## 🎯 Design Principles

|---------|-------------|--------------|```

### Consistency

Every design token follows predictable patterns ensuring a cohesive experience.| **Type Safety** | ✅ Full TypeScript | ⚠️ Via types file |



### Responsive| **Scoped Styles** | ✅ By default | ❌ Global |### Storybook Development

Mobile-first with responsive typography and spacing.

| **Bundle Size** | ✅ Smaller | ⚠️ Full file |

### Accessible

All color combinations meet WCAG 2.1 AA standards.| **Tree Shaking** | ✅ Yes | ❌ No |```bash



### Performance| **CSS Variables** | ✅ Full support | ✅ Full support |npm run storybook

Optimized architecture with efficient imports and tree-shaking support.

| **SCSS Mixins** | ❌ No | ✅ Yes |```

## 📄 License

| **Framework Support** | ✅ Universal | ✅ Universal |

MIT

### Publishing

---

**🎯 Recommendation:** Use CSS Modules for new projects. Use Vanilla SCSS for legacy projects or when you need advanced SCSS features.

**Last Updated:** November 2025 | **Version:** 0.4.0+ | **Repository:** [@shadowfax-tech/sfx-cargo-ui](https://github.com/shadowfax-tech/sfx-cargo-ui)

```bash

## 📁 Directory Structurenpm run prepublishOnly

npm publish

src/lib/styles/

├── css-modules/ # CSS Modules (Recommended)## 📖 What's Included

│ ├── tokens.module.scss # CSS custom properties

│ ├── colors.module.scss # Color utilities### SCSS Modules Support

│ ├── spacing.module.scss # Spacing utilities

│ ├── typography.module.scss # Typography utilitiesThe library now supports SCSS modules for better integration with consumer applications:

│ ├── utils.module.scss # Utility classes

│ └── index.d.ts # TypeScript declarations#### 🎯 CSS Modules

│- Pre-built utility classes exported as CSS modules

├── vanilla/ # Vanilla SCSS (Traditional)- Type-safe imports with TypeScript support

│ ├── complete.scss # Everything in one import- Locally scoped class names prevent style conflicts

│ ├── index.scss # Core design system- Modules available: colors, spacing, typography, utils

│ ├── mixins.scss # SCSS mixins

│ ├── base/ # Base styles#### 🔧 CSS Custom Properties

│ ├── foundations/ # Design tokens- All design tokens exported as CSS variables

│ └── themes/ # Theme definitions- Runtime theme customization

│- Easy integration with any framework

├── base/ # Shared files- Example: var(--sfx-primary-500), var(--sfx-spacing-md)

├── foundations/ # Shared tokens

├── themes/ # Shared themes#### 📦 Module Exports

└── icons/ # Icon configuration```typescript

import colors from '@shadowfax-tech/sfx-ui-theme/styles/modules/colors.module.scss';

## 🎨 Design Tokensimport spacing from '@shadowfax-tech/sfx-ui-theme/styles/modules/spacing.module.scss';

import typography from '@shadowfax-tech/sfx-ui-theme/styles/modules/typography.module.scss';

### Color Tokensimport utils from '@shadowfax-tech/sfx-ui-theme/styles/modules/utils.module.scss';

- Primary: `$sfx-primary-50` to `$sfx-primary-900`

- Neutral: `$sfx-neutral-50` to `$sfx-neutral-900`// CSS Custom Properties

- Semantic: `$sfx-bg-primary`, `$sfx-text-primary`, `$sfx-border-primary`import tokens from '@shadowfax-tech/sfx-ui-theme/styles/tokens.module.scss';

- Status: `$sfx-success-color`, `$sfx-error-color`, `$sfx-warning-color`

// Traditional SCSS

### Spacing Scale@use '@shadowfax-tech/sfx-ui-theme/styles' as sfx;

- Base unit: 4px```

- Semantic: `xs` (4px), `sm` (8px), `md` (16px), `lg` (24px), `xl` (32px), `2xl` (48px), `3xl` (64px)

**📚 See [SCSS Modules Guide](./src/lib/styles/SCSS-MODULES.md) for detailed usage instructions**

### Border Radius

- Values: `none`, `sm`, `base`, `md`, `lg`, `xl`, `2xl`, `3xl`, `full`### Design Tokens



### Typography#### 🎨 **Colors**

- Font family: Inter with system fallbacks- **Primary**: Teal/Green brand colors (#008a71)

- Sizes: Responsive scale from `xs` to `6xl`- **Secondary**: Yellow/Lime accent colors (#d5d226)

- Weights: Thin (100) to Black (900)- **Neutral**: Comprehensive grayscale palette

- Line heights: Paired with each size- **Status**: Success, Warning, Error, Info colors

- **Semantic**: Background, text, border, and icon colors

### Shadows

- Scale: `none`, `xs` through `2xl`#### 📝 **Typography**

- Soft, hard, and glass morphism effects- **Font Family**: Inter (Google Fonts) with system fallbacks

- **Responsive Scale**: Mobile and desktop optimized sizes

## 🧩 Icon Components- **Styles**: Headings (h1-h6), Body text (xl, l, m, s), Utility (label, caption)

- **Properties**: Font sizes, line heights, letter spacing, font weights

380+ pre-built icons in multiple formats:

#### 📏 **Spacing**

**React:**- **Base Unit**: 4px grid system

```tsx- **Scale**: 0px to 384px with logical progression

import { RocketLaunch, Star } from '@shadowfax-tech/sfx-cargo-ui/icons/react';- **Semantic Aliases**: xs, sm, md, lg, xl, 2xl, 3xl for common use cases

<RocketLaunch size={24} color="#3b82f6" />- **Border Radius**: Consistent rounding values (2px to 24px + full)

🌟 Shadows

Angular:- Soft Shadows: Natural, diffused depth effects

<sfx-rocket-launch [size]="24" color="#3b82f6"></sfx-rocket-launch>- **Glass Effects**: Backdrop blur for modern glass-morphism

```- **Utility Shadows**: Pre-configured shadows for common components



**See [Icon Documentation](./src/icons/README.md) for complete guide.**### Component Examples



## 🛠️ Development#### Interactive Examples

- **Buttons**: Primary, secondary, status variants

### Available Scripts- **Cards**: Basic, feature, and status cards

- **Forms**: Complete form layouts with proper spacing

```bash

yarn dev                   # Start Vite dev server## 🛠️ Usage

yarn storybook             # Start Storybook

yarn build                 # Build library### SCSS Integration

yarn build:lib             # Build dist

yarn build-storybook       # Build Storybook for productionImport the design system in your project:

yarn generate-icons        # Generate icons from SVG

``````scss

@import 'sfx-cargo-ui/src/lib/styles/base/index.scss';

### Building```



```bash### Using Design Tokens

yarn build:lib

```#### Colors

```scss

### Publishing.my-component {

  background-color: $sfx-primary-500;

```bash  color: $sfx-neutral-50;

npm run prepublishOnly  border: 1px solid $sfx-border-primary;

npm publish}

📚 Documentation#### Typography

- **README.md** (this file) - Quick start and reference.heading {

- **src/lib/styles/css-modules/README.md** - CSS Modules detailed guide  @include sfx-responsive-font-size(h1);

- **src/lib/styles/vanilla/README.md** - Vanilla SCSS detailed guide  @include sfx-responsive-letter-spacing(h1);

- **src/icons/README.md** - Icon documentation  line-height: map-get($sfx-line-height-data, h1);

- **Storybook** - Interactive explorer (`yarn storybook`)  font-weight: map-get($sfx-font-weight-data, bold);

}

## 🎯 Design Principles```



### Consistency#### Spacing

Every design token follows predictable patterns ensuring a cohesive experience.```scss

.card {

### Responsive  padding: $sfx-spacing-lg;          // 24px

Mobile-first with responsive typography and spacing.  margin-bottom: $sfx-spacing-xl;    // 32px

  gap: map-get($sfx-spacings, 4);    // 16px

### Accessible}

All color combinations meet WCAG 2.1 AA standards.```



### Performance#### Shadows

Optimized architecture with efficient imports and tree-shaking support.```scss

.elevated-card {

## 📄 License  box-shadow: map-get($sfx-shadow-utility-data, card-soft);

}

MIT

.modal {

---  box-shadow: map-get($sfx-shadow-utility-data, modal-soft);

}

**Last Updated:** November 2025 | **Version:** 0.4.0+ | **Repository:** [@shadowfax-tech/sfx-cargo-ui](https://github.com/shadowfax-tech/sfx-cargo-ui)```


#### Border Radius
```scss
.button {
  border-radius: map-get($sfx-radius, md); // 6px
}

.avatar {
  border-radius: map-get($sfx-radius, full); // circular
}

📱 Responsive Design

The design system includes responsive typography that automatically adjusts based on screen size:

• Desktop: 768px and above
• Mobile: Below 768px

Typography mixins handle the responsive behavior automatically:

.responsive-heading {
  @include sfx-responsive-font-size(h1);
  // Outputs: 48px on desktop, 28px on mobile
}

🎯 Design Principles

Consistency

Every design token follows predictable patterns and naming conventions, ensuring a cohesive experience across all touchpoints.

Responsive

Built mobile-first with responsive typography and spacing that adapts beautifully to any screen size.

Accessible

All color combinations meet WCAG 2.1 AA standards, ensuring your interfaces are usable by everyone.

Performance

Optimized SCSS architecture with efficient imports and minimal CSS output for fast loading times.

📁 Project Structure

src/
├── lib/
│   └── styles/
│       ├── base/
│       │   ├── index.scss
│       │   ├── fonts.scss
│       │   └── normalize.scss
│       ├── foundations/
│       │   ├── color/
│       │   │   └── colors.scss
│       │   ├── shadow/
│       │   │   ├── shadows.scss
│       │   │   ├── mixins.scss
│       │   │   └── _functions.scss
│       │   └── typography/
│       │       ├── typography.scss
│       │       ├── mixins.scss
│       │       └── _functions.scss
│       └── themes/
│           ├── default-theme.scss
│           └── index.scss
└── stories/
    ├── Introduction.stories.ts
    ├── Colors.stories.ts
    ├── Typography.stories.ts
    ├── Spacing.stories.ts
    ├── Shadows.stories.ts
    └── Components.stories.ts

🧪 Development

Available Scripts

• yarn dev - Start Vite development server
• yarn build - Build the project
• yarn storybook - Start Storybook development server
• yarn build-storybook - Build Storybook for production

Adding New Stories

Create new .stories.ts files in the src/stories/ directory to document new components or design tokens.

🤝 Contributing

This design system is maintained by the Shadowfax Frontend Team. For questions, suggestions, or contributions, please reach out to the frontend team.