@nithish_kumar_shanigarapu/freightline-design-system

Production-grade React components for enterprise logistics and data-dense applications.

Quick Start

1. Install

npm:

npm install @nithish_kumar_shanigarapu/freightline-design-system

pnpm:

pnpm add @nithish_kumar_shanigarapu/freightline-design-system

2. Import the CSS

Add the design system stylesheet at the root of your application (e.g. main.tsx or _app.tsx):

import '@nithish_kumar_shanigarapu/freightline-design-system/dist/index.css';

3. Use Components

import { Button, Input, StatusBadge } from '@nithish_kumar_shanigarapu/freightline-design-system';

export function MyPage() {
  return (
    <div>
      <StatusBadge status="on-time" />
      <Input placeholder="Track shipment…" />
      <Button variant="primary">Search</Button>
    </div>
  );
}

Tailwind CSS Preset (optional)

If your project uses Tailwind CSS, extend your config with the Freightline preset to get access to all design tokens as utility classes:

// tailwind.config.ts
import { freightlinePreset } from '@nithish_kumar_shanigarapu/freightline-design-system/tailwind-preset';
import type { Config } from 'tailwindcss';

const config: Config = {
  presets: [freightlinePreset],
  content: ['./src/**/*.{ts,tsx}'],
};

export default config;

Component Catalog

The library ships 60+ components organized into six categories.

Forms (13)

Input controls and form primitives for data collection workflows.

| Component | Description | |-----------|-------------| | Button | Primary action trigger with loading, icon, and variant support | | Input | Text input with label, helper text, prefix/suffix, and error state | | Textarea | Multi-line text input with optional auto-resize | | Checkbox | Single boolean control with indeterminate state | | Radio / RadioGroup | Mutually exclusive option selection | | Switch | Toggle control for boolean settings | | Slider | Range selector for numeric values | | NumberInput | Stepper-style numeric input with min/max/step | | Select | Single-value dropdown built on Radix UI Select | | Combobox | Searchable select with options array | | DatePicker | Calendar popover for single date or date range | | FileUpload | Drag-and-drop or click-to-upload file input | | ColorInput | Hex color picker with preset swatches |

Data Display (13)

Components for presenting metrics, statuses, and structured information.

| Component | Description | |-----------|-------------| | Badge | Compact label with semantic color variants | | StatusBadge | Operational status pill with optional indicator dot | | ShipmentStatusBadge | Shipment-specific status badge | | Tag | Removable label chip for categorization | | Avatar | User or entity avatar with status ring and fallback initials | | AvatarGroup | Stacked avatar cluster with overflow count | | Tooltip | Hover/focus disclosure for supplementary context | | StatCard | Single metric card with delta indicator | | KpiCard | KPI tile with sparkline, target, and footer | | Sparkline | Inline mini-chart for trend visualization | | Timeline | Chronological event list with milestone support | | Accordion | Collapsible content sections | | DataTable | Full-featured table with sort, filter, pagination, row selection, and expansion | | Heatmap | Grid-based intensity map for volume or performance data |

Feedback (9)

Notifications, progress indicators, and loading states.

| Component | Description | |-----------|-------------| | Alert / AlertStrip | Inline or banner-style contextual messages | | Banner | Page-level informational or warning strip | | Callout | Highlighted information block within content | | Toast / Toaster | Ephemeral notification system with imperative API | | EmptyState | Zero-data placeholder with icon, headline, and CTA | | Skeleton | Shimmer loading placeholder (text, value, badge, row variants) | | ProgressBar | Linear progress with segmented, indeterminate, and labeled modes | | ProgressRing | Circular progress indicator | | Meter | ARIA meter element with low/high/optimum thresholds |

Navigation (6)

Wayfinding and hierarchical navigation patterns.

| Component | Description | |-----------|-------------| | Sidebar | Collapsible vertical navigation with item groups | | Breadcrumb | Hierarchical location trail | | Tabs | Radix-based tabbed content panels | | NavigationTabs | Pill-style route navigation tabs | | Pagination | Page number controls for large data sets | | Stepper | Multi-step workflow progress indicator |

Overlays (6)

Modal surfaces and floating UI elements.

| Component | Description | |-----------|-------------| | Modal | Accessible dialog with title, body, and footer slots | | Drawer | Side-anchored slide-in panel (left/right/top/bottom) | | Popover | Floating content anchored to a trigger element | | DropdownMenu | Contextual action menu | | ContextMenu | Right-click triggered action menu | | CommandPalette | Keyboard-driven command launcher |

Layout (7)

Structural and compositional layout primitives.

| Component | Description | |-----------|-------------| | AppShell | Full-page application frame with header and sidebar slots | | Card | Elevated container with header, content, and footer slots | | StatGrid | Responsive grid for StatCard layouts | | ChartContainer | Opinionated chart wrapper with title, legend, and loading state | | Divider | Horizontal or vertical separator with optional label | | FilterChip / FilterChipGroup | Active filter pills for query builders | | FilterBar | Managed row of active filter chips with add/clear controls |

Token System

The design system is built on 350+ CSS custom properties organized in a three-layer architecture:

primitive tokens  →  semantic tokens  →  component tokens
(raw values)          (role-based)         (per-component overrides)

Primitive tokens define the raw palette (e.g. --navy-500, --orange-400). Semantic tokens map roles to primitives (e.g. --primary, --destructive, --muted). Component tokens scope overrides to individual components without affecting the rest of the system.

Dark Mode

Dark mode is supported via a .dark class on the <html> element. All semantic tokens automatically resolve to their dark-mode values:

<html class="dark">…</html>

Use the useTheme() hook to toggle programmatically:

import { useTheme } from '@nithish_kumar_shanigarapu/freightline-design-system';

const { isDark, toggleTheme } = useTheme();

Density Modes

Three density modes are available for data-dense vs. spacious layouts. Set the data-density attribute on <html> or any container:

<html data-density="compact">   <!-- tightest -->
<html data-density="cozy">      <!-- default -->
<html data-density="comfortable"> <!-- most spacious -->

Use the useDensity() hook to manage density programmatically:

import { useDensity } from '@nithish_kumar_shanigarapu/freightline-design-system';

const { density, setDensity, cycleForward } = useDensity();

See docs/TOKENS.md for the full token reference.

Theming Guide

Dark Mode

Add the .dark class to the root <html> element:

<html class="dark">

All components and tokens adapt automatically. No additional configuration is required.

Custom Theme

Override semantic CSS variables to apply a custom brand. The most impactful variables to override are:

:root {
  --primary: 222 54% 25%;           /* HSL — primary brand color */
  --secondary: 27 96% 55%;          /* accent / call-to-action */
  --radius: 0.375rem;               /* global border radius */
}

For a full dark-mode override, scope variables under .dark:

.dark {
  --primary: 217 91% 60%;
  --background: 222 54% 9%;
}

Density

Apply the data-density attribute to the <html> element or any subtree to control spacing density:

// Compact — ideal for data grids and dashboards
document.documentElement.dataset.density = 'compact';

// Comfortable — ideal for forms and reading-heavy views
document.documentElement.dataset.density = 'comfortable';

Density affects padding, gap, and line-height throughout all components that consume --density-* tokens.

Accessibility

The Freightline Design System targets WCAG 2.1 AA compliance across all interactive components.

• All interactive components carry correct ARIA roles, aria-label, aria-expanded, aria-disabled, and aria-describedby attributes where required.
• Keyboard navigation is handled by Radix UI primitives (Dialog, Select, Tabs, Toast, and others), ensuring consistent Tab, Arrow, Enter, Escape, and Space behavior across browsers.
• Focus management follows the ARIA Authoring Practices Guide patterns — focus is trapped inside modals and drawers, and restored to the trigger on close.
• Color is never the only indicator of status: status badges, alerts, and meter components use both color and text/icon cues.

Run accessibility audits in Storybook using the @storybook/addon-a11y panel, which is pre-configured in the monorepo.

Contributing

See docs/CONTRIBUTING.md for full guidelines.

Quick start:

# Install all workspace dependencies
pnpm install

# Start Storybook component explorer
pnpm dev

# Run unit tests (Vitest)
pnpm test

All new components must ship with:

• TypeScript props interface with JSDoc comments
• Storybook stories covering default, variants, and edge cases
• Vitest unit tests for key behaviors
• Accessibility story using @storybook/addon-a11y

License

MIT © 2024 Nithish Kumar Shanigarapu