@freightos/freightwind 1.1.0 → 1.1.2

package/dist/cjs/components/alert.js

@@ -88,6 +88,6 @@ const Alert = ({ variant = 'info', title, message, closable = false, onClose, ca
                 setVisible(false);
                 onClose?.();
             }
-        }, children: (0, jsx_runtime_1.jsx)("div", { style: { overflow: 'hidden' }, children: (0, jsx_runtime_1.jsx)(react_1.AnimatePresence, { initial: false, children: !closing && ((0, jsx_runtime_1.jsxs)(react_1.motion.div, { role: "alert", exit: { y: -20 }, transition: { duration: 0.15, ease: 'easeIn' }, className: (0, utils_1.cn)('flex w-full gap-fds-sm rounded-fds-md border-l-4 bg-card pr-fds-sm shadow-[0_0_10px_0_rgba(35,37,55,0.12)]', title ? 'items-start pl-fds-md py-fds-md' : 'items-center pl-fds-lg py-[5px]', config.borderColor), children: [(0, jsx_runtime_1.jsx)(Icon, { size: title ? 20 : 18, className: (0, utils_1.cn)('shrink-0', title && 'mt-[3px]', config.iconColor) }), (0, jsx_runtime_1.jsxs)("div", { className: "flex-1 min-w-0", children: [title && (0, jsx_runtime_1.jsx)("div", { className: "text-fds-h5 font-fds-bold leading-fds-title text-foreground", children: title }), message && ((0, jsx_runtime_1.jsx)("div", { className: (0, utils_1.cn)('text-fds-base text-fds-gray-80 dark:text-white', title && 'mt-fds-xs'), children: message }))] }), showCta && (0, jsx_runtime_1.jsx)("div", { className: "shrink-0", children: callToAction }), showClose && ((0, jsx_runtime_1.jsx)("button", { type: "button", onClick: handleClose, className: "shrink-0 cursor-pointer text-fds-gray-90 hover:text-fds-gray-100 transition-colors", "aria-label": "Close alert", children: (0, jsx_runtime_1.jsx)(icons_1.IconClose, { size: 16 }) }))] })) }) }) }));
+        }, children: (0, jsx_runtime_1.jsx)("div", { style: { overflow: 'hidden' }, children: (0, jsx_runtime_1.jsx)(react_1.AnimatePresence, { initial: false, children: !closing && ((0, jsx_runtime_1.jsxs)(react_1.motion.div, { role: "alert", exit: { y: -20 }, transition: { duration: 0.15, ease: 'easeIn' }, className: (0, utils_1.cn)('flex w-full gap-fds-sm rounded-fds-md border-l-4 bg-card pr-fds-sm shadow-[0_0_10px_0_rgba(35,37,55,0.12)]', title ? 'items-start pl-fds-md py-fds-md' : 'items-center pl-fds-lg py-[5px]', config.borderColor), children: [(0, jsx_runtime_1.jsx)(Icon, { size: title ? 20 : 18, className: (0, utils_1.cn)('shrink-0', title && 'mt-[3px]', config.iconColor) }), (0, jsx_runtime_1.jsxs)("div", { className: "flex-1 min-w-0", children: [title && (0, jsx_runtime_1.jsx)("div", { className: "text-fds-h5 font-fds-bold leading-fds-title text-foreground", children: title }), message && ((0, jsx_runtime_1.jsx)("div", { className: (0, utils_1.cn)('text-fds-base text-fds-gray-80 dark:text-white', title && 'mt-fds-xs'), children: message }))] }), showCta && (0, jsx_runtime_1.jsx)("div", { className: "shrink-0", children: callToAction }), showClose && ((0, jsx_runtime_1.jsx)("button", { type: "button", onClick: handleClose, className: "fw-base shrink-0 cursor-pointer text-fds-gray-90 hover:text-fds-gray-100 transition-colors", "aria-label": "Close alert", children: (0, jsx_runtime_1.jsx)(icons_1.IconClose, { size: 16 }) }))] })) }) }) }));
 };
 exports.Alert = Alert;

package/dist/cjs/components/button.js

@@ -41,7 +41,7 @@ const React = __importStar(require("react"));
 const icon_utils_1 = require("../lib/icon-utils");
 const utils_1 = require("../lib/utils");
 const tooltip_1 = require("./tooltip");
-const buttonVariants = (0, class_variance_authority_1.cva)('inline-flex w-fit items-center justify-center gap-fds-sm whitespace-nowrap rounded-fds-md cursor-pointer transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0', {
+const buttonVariants = (0, class_variance_authority_1.cva)('fw-base inline-flex w-fit items-center justify-center gap-fds-sm whitespace-nowrap rounded-fds-md cursor-pointer transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0', {
     variants: {
         variant: {
             default: 'bg-fds-blue-30 text-fds-white hover:bg-fds-blue-40',

package/dist/cjs/components/checkbox.js

@@ -49,7 +49,7 @@ const Checkbox = React.forwardRef(({ checked, onCheckedChange, disabled, error,
             setInternalChecked(val);
         onCheckedChange?.(val);
     };
-    const box = ((0, jsx_runtime_1.jsx)(CheckboxPrimitive.Root, { ref: ref, id: checkboxId, checked: resolvedChecked, onCheckedChange: handleCheckedChange, disabled: disabled, "aria-invalid": error || undefined, className: (0, utils_1.cn)('peer size-4 shrink-0 rounded-fds-sm border cursor-pointer transition-colors', 'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring', disabled
+    const box = ((0, jsx_runtime_1.jsx)(CheckboxPrimitive.Root, { ref: ref, id: checkboxId, checked: resolvedChecked, onCheckedChange: handleCheckedChange, disabled: disabled, "aria-invalid": error || undefined, className: (0, utils_1.cn)('fw-base peer size-4 shrink-0 rounded-fds-sm border cursor-pointer transition-colors', 'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring', disabled
             ? 'cursor-not-allowed bg-fds-gray-10 border-fds-gray-20'
             : error
                 ? 'border-fds-red-30 bg-fds-red-10 data-[state=checked]:bg-fds-red-30'

package/dist/cjs/components/chip.js

@@ -80,5 +80,5 @@ function Chip({ variant = 'default', icon, closable, onClose, badge, children, }
     };
     const IconComp = icon ? icon_utils_1.iconMap[icon] : null;
     const iconOnly = !!icon && !children;
-    return ((0, jsx_runtime_1.jsxs)("div", { className: (0, utils_1.cn)(chipVariants({ variant }), iconOnly && 'justify-center', badge !== undefined && (typeof badge === 'string' ? badge.length > 0 : badge > 0) && '!pl-0.5'), children: [badge !== undefined && (typeof badge === 'string' ? badge.length > 0 : badge > 0) && ((0, jsx_runtime_1.jsx)("span", { className: (0, utils_1.cn)('mr-1 inline-flex items-center justify-center rounded-full min-w-[16px] h-4 px-1 text-[10px] font-fds-semibold leading-none', badgeColors[variant]), children: typeof badge === 'number' && badge > 99 ? '99+' : badge })), IconComp && (0, jsx_runtime_1.jsx)(IconComp, { size: 12, className: children ? 'mr-fds-sm' : '' }), children, closable && ((0, jsx_runtime_1.jsx)("button", { type: "button", onClick: handleClose, "aria-label": "Remove", className: "ml-fds-sm inline-flex cursor-pointer items-center hover:opacity-70", children: (0, jsx_runtime_1.jsx)(icons_1.IconClose, { size: 10 }) }))] }));
+    return ((0, jsx_runtime_1.jsxs)("div", { className: (0, utils_1.cn)(chipVariants({ variant }), iconOnly && 'justify-center', badge !== undefined && (typeof badge === 'string' ? badge.length > 0 : badge > 0) && '!pl-0.5'), children: [badge !== undefined && (typeof badge === 'string' ? badge.length > 0 : badge > 0) && ((0, jsx_runtime_1.jsx)("span", { className: (0, utils_1.cn)('mr-1 inline-flex items-center justify-center rounded-full min-w-[16px] h-4 px-1 text-[10px] font-fds-semibold leading-none', badgeColors[variant]), children: typeof badge === 'number' && badge > 99 ? '99+' : badge })), IconComp && (0, jsx_runtime_1.jsx)(IconComp, { size: 12, className: children ? 'mr-fds-sm' : '' }), children, closable && ((0, jsx_runtime_1.jsx)("button", { type: "button", onClick: handleClose, "aria-label": "Remove", className: "fw-base ml-fds-sm inline-flex cursor-pointer items-center hover:opacity-70", children: (0, jsx_runtime_1.jsx)(icons_1.IconClose, { size: 10 }) }))] }));
 }

package/dist/cjs/components/radio-group.js

@@ -45,7 +45,7 @@ const RadioGroup = React.forwardRef(({ className, ...props }, ref) => {
 exports.RadioGroup = RadioGroup;
 RadioGroup.displayName = RadioGroupPrimitive.Root.displayName;
 const RadioGroupItem = React.forwardRef(({ className, ...props }, ref) => {
-    return ((0, jsx_runtime_1.jsx)(RadioGroupPrimitive.Item, { ref: ref, className: (0, utils_1.cn)('h-[16px] w-[16px] cursor-pointer rounded-full border border-fds-gray-30 bg-white ring-offset-background focus:outline-none focus-visible:ring-2 focus-visible:ring-fds-blue-30 focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:border-fds-gray-20 disabled:bg-fds-gray-10 data-[state=checked]:border-fds-blue-30 data-[state=checked]:disabled:border-fds-gray-30', className), ...props, children: (0, jsx_runtime_1.jsx)(RadioGroupPrimitive.Indicator, { className: "flex items-center justify-center", children: (0, jsx_runtime_1.jsx)("div", { className: "h-[8px] w-[8px] rounded-full bg-fds-blue-30 [[disabled]_&]:bg-fds-gray-30" }) }) }));
+    return ((0, jsx_runtime_1.jsx)(RadioGroupPrimitive.Item, { ref: ref, className: (0, utils_1.cn)('fw-base h-[16px] w-[16px] cursor-pointer rounded-full border border-fds-gray-30 bg-white ring-offset-background focus:outline-none focus-visible:ring-2 focus-visible:ring-fds-blue-30 focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:border-fds-gray-20 disabled:bg-fds-gray-10 data-[state=checked]:border-fds-blue-30 data-[state=checked]:disabled:border-fds-gray-30', className), ...props, children: (0, jsx_runtime_1.jsx)(RadioGroupPrimitive.Indicator, { className: "flex items-center justify-center", children: (0, jsx_runtime_1.jsx)("div", { className: "h-[8px] w-[8px] rounded-full bg-fds-blue-30 [[disabled]_&]:bg-fds-gray-30" }) }) }));
 });
 exports.RadioGroupItem = RadioGroupItem;
 RadioGroupItem.displayName = RadioGroupPrimitive.Item.displayName;

package/dist/cjs/components/switch.js

@@ -41,7 +41,7 @@ const React = __importStar(require("react"));
 const class_variance_authority_1 = require("class-variance-authority");
 const utils_1 = require("../lib/utils");
 const use_stable_id_1 = require("../lib/use-stable-id");
-const switchVariants = (0, class_variance_authority_1.cva)('peer inline-flex shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-fds-blue-30 focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50', {
+const switchVariants = (0, class_variance_authority_1.cva)('fw-base peer inline-flex shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-fds-blue-30 focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50', {
     variants: {
         size: {
             lg: 'h-5 w-9',

package/dist/esm/components/alert.js

@@ -52,5 +52,5 @@ export const Alert = ({ variant = 'info', title, message, closable = false, onCl
                 setVisible(false);
                 onClose?.();
             }
-        }, children: _jsx("div", { style: { overflow: 'hidden' }, children: _jsx(AnimatePresence, { initial: false, children: !closing && (_jsxs(motion.div, { role: "alert", exit: { y: -20 }, transition: { duration: 0.15, ease: 'easeIn' }, className: cn('flex w-full gap-fds-sm rounded-fds-md border-l-4 bg-card pr-fds-sm shadow-[0_0_10px_0_rgba(35,37,55,0.12)]', title ? 'items-start pl-fds-md py-fds-md' : 'items-center pl-fds-lg py-[5px]', config.borderColor), children: [_jsx(Icon, { size: title ? 20 : 18, className: cn('shrink-0', title && 'mt-[3px]', config.iconColor) }), _jsxs("div", { className: "flex-1 min-w-0", children: [title && _jsx("div", { className: "text-fds-h5 font-fds-bold leading-fds-title text-foreground", children: title }), message && (_jsx("div", { className: cn('text-fds-base text-fds-gray-80 dark:text-white', title && 'mt-fds-xs'), children: message }))] }), showCta && _jsx("div", { className: "shrink-0", children: callToAction }), showClose && (_jsx("button", { type: "button", onClick: handleClose, className: "shrink-0 cursor-pointer text-fds-gray-90 hover:text-fds-gray-100 transition-colors", "aria-label": "Close alert", children: _jsx(IconClose, { size: 16 }) }))] })) }) }) }));
+        }, children: _jsx("div", { style: { overflow: 'hidden' }, children: _jsx(AnimatePresence, { initial: false, children: !closing && (_jsxs(motion.div, { role: "alert", exit: { y: -20 }, transition: { duration: 0.15, ease: 'easeIn' }, className: cn('flex w-full gap-fds-sm rounded-fds-md border-l-4 bg-card pr-fds-sm shadow-[0_0_10px_0_rgba(35,37,55,0.12)]', title ? 'items-start pl-fds-md py-fds-md' : 'items-center pl-fds-lg py-[5px]', config.borderColor), children: [_jsx(Icon, { size: title ? 20 : 18, className: cn('shrink-0', title && 'mt-[3px]', config.iconColor) }), _jsxs("div", { className: "flex-1 min-w-0", children: [title && _jsx("div", { className: "text-fds-h5 font-fds-bold leading-fds-title text-foreground", children: title }), message && (_jsx("div", { className: cn('text-fds-base text-fds-gray-80 dark:text-white', title && 'mt-fds-xs'), children: message }))] }), showCta && _jsx("div", { className: "shrink-0", children: callToAction }), showClose && (_jsx("button", { type: "button", onClick: handleClose, className: "fw-base shrink-0 cursor-pointer text-fds-gray-90 hover:text-fds-gray-100 transition-colors", "aria-label": "Close alert", children: _jsx(IconClose, { size: 16 }) }))] })) }) }) }));
 };

package/dist/esm/components/button.js

@@ -5,7 +5,7 @@ import * as React from 'react';
 import { iconMap } from '../lib/icon-utils';
 import { cn } from '../lib/utils';
 import { Tooltip } from './tooltip';
-const buttonVariants = cva('inline-flex w-fit items-center justify-center gap-fds-sm whitespace-nowrap rounded-fds-md cursor-pointer transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0', {
+const buttonVariants = cva('fw-base inline-flex w-fit items-center justify-center gap-fds-sm whitespace-nowrap rounded-fds-md cursor-pointer transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0', {
     variants: {
         variant: {
             default: 'bg-fds-blue-30 text-fds-white hover:bg-fds-blue-40',

package/dist/esm/components/checkbox.js

@@ -13,7 +13,7 @@ const Checkbox = React.forwardRef(({ checked, onCheckedChange, disabled, error,
             setInternalChecked(val);
         onCheckedChange?.(val);
     };
-    const box = (_jsx(CheckboxPrimitive.Root, { ref: ref, id: checkboxId, checked: resolvedChecked, onCheckedChange: handleCheckedChange, disabled: disabled, "aria-invalid": error || undefined, className: cn('peer size-4 shrink-0 rounded-fds-sm border cursor-pointer transition-colors', 'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring', disabled
+    const box = (_jsx(CheckboxPrimitive.Root, { ref: ref, id: checkboxId, checked: resolvedChecked, onCheckedChange: handleCheckedChange, disabled: disabled, "aria-invalid": error || undefined, className: cn('fw-base peer size-4 shrink-0 rounded-fds-sm border cursor-pointer transition-colors', 'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring', disabled
             ? 'cursor-not-allowed bg-fds-gray-10 border-fds-gray-20'
             : error
                 ? 'border-fds-red-30 bg-fds-red-10 data-[state=checked]:bg-fds-red-30'

package/dist/esm/components/chip.js

@@ -42,6 +42,6 @@ function Chip({ variant = 'default', icon, closable, onClose, badge, children, }
     };
     const IconComp = icon ? iconMap[icon] : null;
     const iconOnly = !!icon && !children;
-    return (_jsxs("div", { className: cn(chipVariants({ variant }), iconOnly && 'justify-center', badge !== undefined && (typeof badge === 'string' ? badge.length > 0 : badge > 0) && '!pl-0.5'), children: [badge !== undefined && (typeof badge === 'string' ? badge.length > 0 : badge > 0) && (_jsx("span", { className: cn('mr-1 inline-flex items-center justify-center rounded-full min-w-[16px] h-4 px-1 text-[10px] font-fds-semibold leading-none', badgeColors[variant]), children: typeof badge === 'number' && badge > 99 ? '99+' : badge })), IconComp && _jsx(IconComp, { size: 12, className: children ? 'mr-fds-sm' : '' }), children, closable && (_jsx("button", { type: "button", onClick: handleClose, "aria-label": "Remove", className: "ml-fds-sm inline-flex cursor-pointer items-center hover:opacity-70", children: _jsx(IconClose, { size: 10 }) }))] }));
+    return (_jsxs("div", { className: cn(chipVariants({ variant }), iconOnly && 'justify-center', badge !== undefined && (typeof badge === 'string' ? badge.length > 0 : badge > 0) && '!pl-0.5'), children: [badge !== undefined && (typeof badge === 'string' ? badge.length > 0 : badge > 0) && (_jsx("span", { className: cn('mr-1 inline-flex items-center justify-center rounded-full min-w-[16px] h-4 px-1 text-[10px] font-fds-semibold leading-none', badgeColors[variant]), children: typeof badge === 'number' && badge > 99 ? '99+' : badge })), IconComp && _jsx(IconComp, { size: 12, className: children ? 'mr-fds-sm' : '' }), children, closable && (_jsx("button", { type: "button", onClick: handleClose, "aria-label": "Remove", className: "fw-base ml-fds-sm inline-flex cursor-pointer items-center hover:opacity-70", children: _jsx(IconClose, { size: 10 }) }))] }));
 }
 export { Chip, chipVariants };

package/dist/esm/components/radio-group.js

@@ -8,7 +8,7 @@ const RadioGroup = React.forwardRef(({ className, ...props }, ref) => {
 });
 RadioGroup.displayName = RadioGroupPrimitive.Root.displayName;
 const RadioGroupItem = React.forwardRef(({ className, ...props }, ref) => {
-    return (_jsx(RadioGroupPrimitive.Item, { ref: ref, className: cn('h-[16px] w-[16px] cursor-pointer rounded-full border border-fds-gray-30 bg-white ring-offset-background focus:outline-none focus-visible:ring-2 focus-visible:ring-fds-blue-30 focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:border-fds-gray-20 disabled:bg-fds-gray-10 data-[state=checked]:border-fds-blue-30 data-[state=checked]:disabled:border-fds-gray-30', className), ...props, children: _jsx(RadioGroupPrimitive.Indicator, { className: "flex items-center justify-center", children: _jsx("div", { className: "h-[8px] w-[8px] rounded-full bg-fds-blue-30 [[disabled]_&]:bg-fds-gray-30" }) }) }));
+    return (_jsx(RadioGroupPrimitive.Item, { ref: ref, className: cn('fw-base h-[16px] w-[16px] cursor-pointer rounded-full border border-fds-gray-30 bg-white ring-offset-background focus:outline-none focus-visible:ring-2 focus-visible:ring-fds-blue-30 focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:border-fds-gray-20 disabled:bg-fds-gray-10 data-[state=checked]:border-fds-blue-30 data-[state=checked]:disabled:border-fds-gray-30', className), ...props, children: _jsx(RadioGroupPrimitive.Indicator, { className: "flex items-center justify-center", children: _jsx("div", { className: "h-[8px] w-[8px] rounded-full bg-fds-blue-30 [[disabled]_&]:bg-fds-gray-30" }) }) }));
 });
 RadioGroupItem.displayName = RadioGroupPrimitive.Item.displayName;
 export { RadioGroup, RadioGroupItem };

package/dist/esm/components/switch.js

@@ -5,7 +5,7 @@ import * as React from 'react';
 import { cva } from 'class-variance-authority';
 import { cn } from '../lib/utils';
 import { useStableId } from '../lib/use-stable-id';
-const switchVariants = cva('peer inline-flex shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-fds-blue-30 focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50', {
+const switchVariants = cva('fw-base peer inline-flex shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-fds-blue-30 focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50', {
     variants: {
         size: {
             lg: 'h-5 w-9',

package/guidelines/Guidelines.md

@@ -0,0 +1,141 @@
+# FreightWind Design System
+
+FreightWind is the Freightos Design System — a React component library styled with Tailwind CSS v4 and FDS (Freightos Design System) tokens.
+
+## Complete Setup
+
+Follow ALL steps below to properly set up FreightWind in a React project.
+
+### Step 1 — Install dependencies
+
+```bash
+npm install @freightos/freightwind @freightos/icons
+```
+
+`@freightos/icons` is a required peer dependency that provides all iconography.
+
+### Step 2 — Load the Open Sans font
+
+FreightWind uses **Open Sans** as its font family. Load it from Google Fonts.
+
+**Option A — In your HTML `<head>`:**
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link href="https://fonts.googleapis.com/css2?family=Open+Sans:wght@400;600;700&display=swap" rel="stylesheet" />
+```
+
+**Option B — In Next.js with `next/font`:**
+
+```tsx
+import { Open_Sans } from 'next/font/google';
+
+const openSans = Open_Sans({
+  subsets: ['latin'],
+  weight: ['400', '600', '700'],
+  variable: '--font-open-sans',
+});
+
+// Apply to <html> or <body>:
+<html className={openSans.variable}>
+```
+
+Then in your CSS, override the font-sans variable:
+
+```css
+@theme inline {
+  --font-sans: var(--font-open-sans), 'Open Sans', ui-sans-serif, system-ui, sans-serif;
+}
+```
+
+### Step 3 — Import tokens CSS
+
+Import the FreightWind tokens stylesheet in your global CSS file. This provides all design tokens, color variables, and custom utilities:
+
+```css
+@import "@freightos/freightwind/tokens.css";
+```
+
+### Step 4 — Set up global body styles
+
+Add these base styles in your global CSS. These are REQUIRED for components to render correctly:
+
+```css
+* {
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+body {
+  background-color: var(--ground);
+  color: var(--foreground);
+  font-family: 'Open Sans', ui-sans-serif, system-ui, -apple-system, sans-serif;
+  font-size: 0.875rem; /* 14px — FDS base font size */
+  line-height: 1.5;
+}
+```
+
+The `--ground` color is `#f6f6f6` (light gray page canvas). The `--foreground` color is `#3b3f4b` (dark gray text).
+
+Font smoothing (`antialiased`) MUST be applied globally — without it, text will look inconsistent across browsers.
+
+### Step 5 — Import and use components
+
+```tsx
+import { Button, Alert, Checkbox } from '@freightos/freightwind';
+import { IconSearch } from '@freightos/icons';
+
+<Button variant="default" size="md">Submit</Button>
+<Alert variant="info" message="Shipment updated." />
+<Checkbox>Accept terms</Checkbox>
+```
+
+### Step 6 — Toast notifications (optional)
+
+If using the `message` toast API, wrap your app with `MessageProvider`:
+
+```tsx
+import { MessageProvider, message } from '@freightos/freightwind';
+
+// In your root layout:
+<MessageProvider />
+
+// Anywhere in your app:
+message.success('Saved successfully');
+```
+
+## Tailwind CSS requirement
+
+FreightWind components use Tailwind CSS v4 utility classes. Your project MUST have Tailwind CSS v4 configured. The `tokens.css` file provides all necessary theme tokens and custom utilities needed by the components.
+
+If your project uses Tailwind without preflight (to avoid resetting existing components), FreightWind still works — components carry their own element resets via the `fw-base` utility class.
+
+## Dark mode
+
+FreightWind supports dark mode via a `.dark` class on a parent element (typically `<html>`). The tokens.css includes dark mode overrides for all semantic colors. To enable dark mode, add `class="dark"` to the `<html>` element.
+
+## Available components
+
+See `overview-components.md` for a full list of components with their props and usage.
+
+## Available icons
+
+See `overview-icons.md` for details on the icon system.
+
+## Design tokens
+
+FreightWind uses a custom token system instead of Tailwind defaults:
+
+- **Colors**: `design-tokens/colors.md` — semantic color palette (blue, red, green, yellow, gray, purple)
+- **Typography**: `design-tokens/typography.md` — font family, sizes, weights, and line heights
+- **Spacing**: `design-tokens/spacing.md` — consistent spacing scale
+
+## Key conventions
+
+- Always use FDS tokens (`text-fds-*`, `p-fds-*`, `rounded-fds-*`, `bg-fds-*`) instead of Tailwind defaults
+- All components support both controlled and uncontrolled usage patterns
+- Components with `icon` props accept kebab-case icon names: `"search"`, `"close"`, `"user"`, `"risk"`, etc.
+- Use `cn()` utility (exported from the package) for className merging
+- The page canvas background should be `bg-ground` (#f6f6f6), not white
+- Cards and content areas use `bg-card` (#ffffff) against the ground

package/guidelines/design-tokens/colors.md

@@ -0,0 +1,81 @@
+# Color Tokens
+
+FreightWind uses the FDS (Freightos Design System) color palette. Always use FDS color tokens instead of Tailwind defaults.
+
+## Primary — Blue
+
+The primary action color. Use for buttons, links, and interactive elements.
+
+| Token | Class | Usage |
+|-------|-------|-------|
+| Blue 05 | `bg-fds-blue-05` | Disabled checked state |
+| Blue 10 | `bg-fds-blue-10` | Hover backgrounds, selected states |
+| Blue 20 | `bg-fds-blue-20` | Light accent backgrounds |
+| Blue 30 | `bg-fds-blue-30`, `text-fds-blue-30` | Primary action color (default) |
+| Blue 40 | `bg-fds-blue-40`, `text-fds-blue-40` | Hover state for primary actions |
+| Blue 50 | `bg-fds-blue-50` | Active/pressed state |
+
+## Semantic — Red (Error/Danger)
+
+| Token | Class | Usage |
+|-------|-------|-------|
+| Red 10 | `bg-fds-red-10` | Error background tint |
+| Red 20 | `bg-fds-red-20` | Error chip background |
+| Red 30 | `bg-fds-red-30`, `text-fds-red-30` | Error/danger primary |
+| Red 40 | `bg-fds-red-40` | Error hover state |
+
+## Semantic — Green (Success)
+
+| Token | Class | Usage |
+|-------|-------|-------|
+| Green 20 | `bg-fds-green-20` | Success background tint |
+| Green 30 | `bg-fds-green-30`, `text-fds-green-30` | Success primary |
+| Green 40 | `bg-fds-green-40` | Success strong |
+
+## Semantic — Yellow (Warning)
+
+| Token | Class | Usage |
+|-------|-------|-------|
+| Yellow 20 | `bg-fds-yellow-20` | Warning background tint |
+| Yellow 30 | `bg-fds-yellow-30`, `text-fds-yellow-30` | Warning primary |
+| Yellow 50 | `bg-fds-yellow-50` | Warning strong |
+
+## Gray Scale
+
+Use for text, borders, backgrounds, and disabled states.
+
+| Token | Class | Usage |
+|-------|-------|-------|
+| Gray 05 | `bg-fds-gray-05` | Lightest background |
+| Gray 10 | `bg-fds-gray-10` | Disabled background |
+| Gray 20 | `bg-fds-gray-20` | Disabled borders, light backgrounds |
+| Gray 30 | `bg-fds-gray-30` | Default borders |
+| Gray 40 | `bg-fds-gray-40` | Muted icons |
+| Gray 60 | `bg-fds-gray-60`, `text-fds-gray-60` | Disabled text, secondary text |
+| Gray 80 | `text-fds-gray-80` | Body text |
+| Gray 90 | `text-fds-gray-90` | Dark text |
+| Gray 100 | `text-fds-gray-100`, `bg-fds-gray-100` | Darkest text, tooltip bg |
+
+## Accent — Purple
+
+| Token | Class | Usage |
+|-------|-------|-------|
+| Purple 1 | `text-fds-purple-1` | Accent text |
+| Purple 2 | `bg-fds-purple-2` | Accent background |
+
+## White
+
+| Token | Class | Usage |
+|-------|-------|-------|
+| White | `text-fds-white`, `bg-fds-white` | White text/backgrounds |
+
+## Decision guide
+
+- **Primary actions** (buttons, links): `fds-blue-30`
+- **Destructive actions**: `fds-red-30`
+- **Success states**: `fds-green-30`
+- **Warning states**: `fds-yellow-30`
+- **Body text**: `fds-gray-80`
+- **Disabled text**: `fds-gray-60`
+- **Borders**: `fds-gray-30` (default), `fds-gray-20` (disabled)
+- **Page background**: `bg-ground`

package/guidelines/design-tokens/spacing.md

@@ -0,0 +1,45 @@
+# Spacing Tokens
+
+FreightWind uses FDS spacing tokens for consistent sizing. Use these instead of Tailwind defaults.
+
+## Spacing scale
+
+| Token | Class prefix | Size | Usage |
+|-------|-------------|------|-------|
+| XS | `p-fds-xs`, `m-fds-xs`, `gap-fds-xs` | 4px | Tight spacing (icon gaps, small padding) |
+| SM | `p-fds-sm`, `m-fds-sm`, `gap-fds-sm` | 8px | Default component internal spacing |
+| MD | `p-fds-md`, `m-fds-md`, `gap-fds-md` | 12px | Medium padding, form field spacing |
+| LG | `p-fds-lg`, `m-fds-lg`, `gap-fds-lg` | 16px | Section padding, card padding |
+| XL | `p-fds-xl`, `m-fds-xl`, `gap-fds-xl` | 24px | Large section spacing |
+| XXL | `p-fds-xxl`, `m-fds-xxl`, `gap-fds-xxl` | 32px | Page-level spacing |
+
+All spacing tokens work with Tailwind's full set of utility prefixes: `p-`, `px-`, `py-`, `pt-`, `pr-`, `pb-`, `pl-`, `m-`, `mx-`, `my-`, `mt-`, `mr-`, `mb-`, `ml-`, `gap-`, `gap-x-`, `gap-y-`.
+
+## Border radius
+
+| Token | Class | Value | Usage |
+|-------|-------|-------|-------|
+| SM | `rounded-fds-sm` | 2px | Checkboxes, small elements |
+| MD | `rounded-fds-md` | 4px | Buttons, inputs, cards |
+| LG | `rounded-fds-lg` | 8px | Modals, popovers |
+
+## Shadows
+
+| Token | Class | Usage |
+|-------|-------|-------|
+| SM | `shadow-fds-sm` | Subtle elevation (dropdowns) |
+| MD | `shadow-fds-md` | Medium elevation (cards, popovers) |
+| LG | `shadow-fds-lg` | High elevation (modals) |
+
+## Usage example
+
+```tsx
+<div className="p-fds-lg rounded-fds-md shadow-fds-sm">
+  <h2 className="mb-fds-sm text-fds-h5 font-fds-bold">Card Title</h2>
+  <p className="text-fds-base text-fds-gray-80">Card content with consistent spacing.</p>
+  <div className="mt-fds-md flex gap-fds-sm">
+    <Button variant="default">Confirm</Button>
+    <Button variant="secondary">Cancel</Button>
+  </div>
+</div>
+```

package/guidelines/design-tokens/typography.md

@@ -0,0 +1,87 @@
+# Typography Tokens
+
+FreightWind uses FDS typography tokens. Always use these instead of Tailwind default sizes.
+
+## Font family
+
+FreightWind uses **Open Sans** (Google Fonts). The font must be loaded externally and applied to the body:
+
+```css
+body {
+  font-family: 'Open Sans', ui-sans-serif, system-ui, -apple-system, sans-serif;
+}
+```
+
+The tokens.css defines `--font-sans: 'Open Sans', ui-sans-serif, system-ui, sans-serif` which maps to Tailwind's `font-sans` utility. You can use `className="font-sans"` to apply it, but it's better to set it on the body element directly.
+
+Required font weights: **400** (regular), **600** (semibold), **700** (bold).
+
+## Font smoothing
+
+All text MUST have antialiased font smoothing. Apply globally:
+
+```css
+* {
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+```
+
+Without this, text rendering will look inconsistent across browsers, especially on macOS.
+
+## Base font size
+
+The default body font size is **14px** (`0.875rem`), not the browser default 16px:
+
+```css
+body {
+  font-size: 0.875rem;
+}
+```
+
+## Font sizes
+
+| Token | Class | Size | Usage |
+|-------|-------|------|-------|
+| XS | `text-fds-xs` | 10px | Captions, fine print |
+| SM | `text-fds-sm` | 12px | Small labels, badges, chips |
+| Base | `text-fds-base` | 14px | Body text (default) |
+| H6 | `text-fds-h6` | 16px | Small headings, large labels |
+| H5 | `text-fds-h5` | 18px | Section headings |
+| H4 | `text-fds-h4` | 22px | Page sub-headings |
+| H3 | `text-fds-h3` | 24px | Page headings |
+| H2 | `text-fds-h2` | 32px | Major headings |
+| H1 | `text-fds-h1` | 40px | Hero headings |
+
+## Font weights
+
+| Token | Class | Weight | Usage |
+|-------|-------|--------|-------|
+| Regular | `font-fds-regular` | 400 | Body text |
+| Semibold | `font-fds-semibold` | 600 | Labels, emphasis |
+| Bold | `font-fds-bold` | 700 | Headings, strong emphasis |
+
+## Line heights
+
+| Token | Class | Value | Usage |
+|-------|-------|-------|-------|
+| Title | `leading-fds-title` | 1.25 | Headings (h1-h6) |
+| Body | `leading-fds-body` | 1.5 | Body text, paragraphs |
+
+## Usage patterns
+
+```tsx
+// Page heading
+<h1 className="text-fds-h3 font-fds-bold leading-fds-title text-foreground">Page Title</h1>
+
+// Body text
+<p className="text-fds-base text-fds-gray-80">Body content here.</p>
+
+// Small label
+<span className="text-fds-sm font-fds-semibold text-fds-gray-60">Label</span>
+
+// Caption
+<span className="text-fds-xs text-fds-gray-60">Fine print</span>
+```
+
+Heading size classes (`text-fds-h1` through `text-fds-h6`) set font-size only. Always pair with `leading-fds-title` for proper line height.

package/guidelines/overview-components.md

@@ -0,0 +1,252 @@
+# Components Overview
+
+## Component list
+
+| Component | Purpose | Key props |
+|-----------|---------|-----------|
+| `Button` | Primary action trigger | `variant`, `size`, `icon`, `loading`, `tooltip`, `fullWidth` |
+| `Alert` | Contextual feedback banner | `variant`, `title`, `message`, `closable`, `callToAction` |
+| `Avatar` | User or entity representation | `variant`, `size`, `icon`, `title`, `flag`, `src` |
+| `Badge` | Numeric indicator or status dot | `value`, `size`, `variant`, `status`, `text` |
+| `Checkbox` | Boolean or indeterminate toggle | `checked`, `onCheckedChange`, `disabled`, `error`, `children` |
+| `Chip` | Compact label with optional badge | `variant`, `icon`, `closable`, `badge`, `children` |
+| `MessageProvider` / `message` | Toast notifications | Provider wraps app; `message.success()`, `.info()`, `.warning()`, `.error()` |
+| `PopConfirm` | Confirmation popover | `title`, `onConfirm`, `onCancel`, `placement`, `slotProps` |
+| `RadioButtonGroup` | Segmented button selection | `options`, `value`, `onValueChange`, `size`, `orientation` |
+| `RadioGroup` / `RadioGroupItem` | Traditional radio selection | Standard Radix RadioGroup API |
+| `Slider` | Range value selector | `value`, `onValueChange`, `min`, `max`, `step` |
+| `Switch` | On/off toggle | `checked`, `onCheckedChange`, `disabled`, `error`, `size`, `children` |
+| `Tooltip` | Contextual hover information | `message`, `placement`, `children` |
+
+## Button
+
+The most commonly used component. Always use `Button` for clickable actions.
+
+```tsx
+import { Button } from '@freightos/freightwind';
+
+// Primary action
+<Button variant="default" size="md">Submit</Button>
+
+// Secondary action
+<Button variant="secondary">Cancel</Button>
+
+// Danger action
+<Button variant="danger">Delete</Button>
+
+// Icon-only button (tooltip is required)
+<Button icon="search" tooltip="Search" />
+
+// Loading state
+<Button loading>Saving...</Button>
+
+// Toggle button
+<Button variant="toggle" active={isActive}>Grid View</Button>
+```
+
+**Variants**: `default` (primary blue), `secondary` (outlined blue), `tertiary` (text-only blue), `link` (text link), `danger` (red), `danger-ghost` (outlined red), `toggle` (gray border, blue when active).
+
+**Sizes**: `sm` (24px height), `md` (32px height, default), `lg` (40px height).
+
+**Icon-only buttons** must have a `tooltip` prop for accessibility. Pass icon names in kebab-case: `icon="search"`, `icon="close"`, `icon="settings"`.
+
+## Alert
+
+Contextual feedback banner with icon, optional title, message, and close button.
+
+```tsx
+import { Alert } from '@freightos/freightwind';
+
+// Simple message-only alert
+<Alert variant="info" message="Your shipment has been updated." />
+
+// Alert with title
+<Alert variant="warning" title="Attention" message="Rate expires in 24 hours." />
+
+// Closable alert
+<Alert variant="success" message="Saved!" closable onClose={() => {}} />
+
+// Alert with call-to-action (only when no title)
+<Alert variant="error" message="Connection failed." callToAction={<Button size="sm" variant="danger">Retry</Button>} />
+```
+
+**Variants**: `info` (blue), `success` (green), `warning` (yellow), `error` (red), `special` (purple).
+
+## Avatar
+
+User or entity representation. Content priority: `src` > `flag` > `title` > `icon` > default user placeholder.
+
+```tsx
+import { Avatar } from '@freightos/freightwind';
+
+// Image avatar
+<Avatar src="https://example.com/photo.jpg" alt="John" />
+
+// Country flag
+<Avatar flag="US" />
+
+// Initial letter
+<Avatar title="John Doe" />
+
+// Icon avatar
+<Avatar icon="settings" variant="info" />
+
+// Sized avatar
+<Avatar title="JD" size="lg" bordered />
+```
+
+**Sizes**: `xs` (16px), `sm` (24px), `md` (32px, default), `lg` (40px), `xl` (58px).
+
+**Variants**: `default` (purple), `info` (blue), `secondary` (light blue), `warning` (yellow), `neutral` (gray), `positive` (green), `filled` (white bg), `ghost` (transparent).
+
+## Badge
+
+Numeric indicator or status dot. Can wrap a child element for positioning.
+
+```tsx
+import { Badge } from '@freightos/freightwind';
+
+// Standalone count badge
+<Badge value={5} />
+
+// Badge wrapping an icon/button
+<Badge value={3}><IconBell size={20} /></Badge>
+
+// Status dot with text
+<Badge status="success" text="Active" />
+
+// Numbers over 99 display as "99+"
+<Badge value={150} />
+```
+
+## Checkbox
+
+Boolean or indeterminate toggle with optional label.
+
+```tsx
+import { Checkbox } from '@freightos/freightwind';
+
+// With label
+<Checkbox checked={value} onCheckedChange={setValue}>Accept terms</Checkbox>
+
+// Without label
+<Checkbox checked={value} onCheckedChange={setValue} />
+
+// Indeterminate state
+<Checkbox checked="indeterminate" onCheckedChange={setValue}>Select all</Checkbox>
+
+// Error state
+<Checkbox error>Required field</Checkbox>
+```
+
+## Chip
+
+Compact label with optional icon, badge, and close button.
+
+```tsx
+import { Chip } from '@freightos/freightwind';
+
+// Basic chip
+<Chip>Active</Chip>
+
+// With variant and icon
+<Chip variant="success" icon="check-circled">Approved</Chip>
+
+// With badge count
+<Chip variant="info" badge={3}>Notifications</Chip>
+
+// Closable
+<Chip closable onClose={() => {}}>Filter</Chip>
+```
+
+**Variants**: `default` (purple), `neutral` (gray), `info` (light blue), `highlight` (bright blue), `warning` (yellow), `success` (green), `notice` (light red), `error` (red).
+
+## Switch
+
+On/off toggle with optional label.
+
+```tsx
+import { Switch } from '@freightos/freightwind';
+
+// With label
+<Switch checked={value} onCheckedChange={setValue}>Enable notifications</Switch>
+
+// Without label
+<Switch checked={value} onCheckedChange={setValue} />
+
+// Sizes
+<Switch size="sm">Small switch</Switch>
+<Switch size="lg">Large switch</Switch>
+```
+
+## RadioButtonGroup
+
+Segmented button selector. Use for choosing between 2-5 mutually exclusive options.
+
+```tsx
+import { RadioButtonGroup } from '@freightos/freightwind';
+
+<RadioButtonGroup
+  options={[
+    { value: 'list', label: 'List' },
+    { value: 'grid', label: 'Grid' },
+    { value: 'map', label: 'Map' },
+  ]}
+  value={view}
+  onValueChange={setView}
+  size="md"
+/>
+```
+
+## Slider
+
+Range value selector.
+
+```tsx
+import { Slider } from '@freightos/freightwind';
+
+<Slider value={[50]} onValueChange={setValue} min={0} max={100} step={1} />
+```
+
+## Tooltip
+
+Hover tooltip. Wraps any element.
+
+```tsx
+import { Tooltip } from '@freightos/freightwind';
+
+<Tooltip message="Click to save" placement="top">
+  <Button>Save</Button>
+</Tooltip>
+```
+
+**Placements**: `top`, `bottom`, `start`, `end`, `top-start`, `top-end`, `bottom-start`, `bottom-end`.
+
+## PopConfirm
+
+Confirmation popover. Wraps a trigger element.
+
+```tsx
+import { PopConfirm } from '@freightos/freightwind';
+
+<PopConfirm title="Are you sure you want to delete this?" onConfirm={handleDelete}>
+  <Button variant="danger">Delete</Button>
+</PopConfirm>
+```
+
+## MessageProvider / message
+
+Toast notification system. Add `MessageProvider` once at the app root, then call `message.*()` anywhere.
+
+```tsx
+import { MessageProvider, message } from '@freightos/freightwind';
+
+// In your root layout:
+<MessageProvider />
+
+// Anywhere in your app:
+message.success('Shipment created successfully');
+message.error('Failed to save changes');
+message.warning('Rate expires soon');
+message.info('New update available');
+```

package/guidelines/overview-icons.md

@@ -0,0 +1,52 @@
+# Icons
+
+FreightWind uses `@freightos/icons` as a peer dependency for all iconography.
+
+## Direct icon imports
+
+For standalone icon usage, import directly from `@freightos/icons`:
+
+```tsx
+import { IconSearch, IconClose, IconUser, IconRisk } from '@freightos/icons';
+
+<IconSearch size={16} />
+<IconClose size={20} className="text-fds-gray-80" />
+```
+
+All icons accept `size` (number, in px) and `className` props. Icons inherit `currentColor` by default.
+
+## Icon prop on components
+
+Components like `Button`, `Avatar`, and `Chip` accept an `icon` prop with a kebab-case name string:
+
+```tsx
+<Button icon="search" tooltip="Search" />
+<Avatar icon="settings" />
+<Chip icon="check-circled">Done</Chip>
+```
+
+Do NOT pass React components to the `icon` prop — use the kebab-case string name.
+
+## Common icon names
+
+| Name | Component | Usage |
+|------|-----------|-------|
+| `search` | `IconSearch` | Search actions |
+| `close` | `IconClose` | Close/dismiss actions |
+| `user` | `IconUser` | User profiles |
+| `settings` | `IconSettings` | Settings/gear |
+| `risk` | `IconRisk` | Warning/caution |
+| `check-circled` | `IconCheckCircled` | Success/confirmation |
+| `info-circled` | `IconInfoCircled` | Information |
+| `negative-circled` | `IconNegativeCircled` | Error/negative |
+| `arrow-down` | `IconArrowDown` | Directional |
+| `arrow-up` | `IconArrowUp` | Directional |
+| `edit` | `IconEdit` | Edit actions |
+| `delete` | `IconDelete` | Delete actions |
+| `download` | `IconDownload` | Download actions |
+| `upload` | `IconUpload` | Upload actions |
+| `bookmark` | `IconBookmark` | Bookmark/save |
+
+## Icon style
+
+All icons use stroke-only outlines (`stroke="currentColor"`). They are designed at 24px but scale cleanly to any size.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@freightos/freightwind",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "private": false,
   "description": "FreightWind Design System — React UI components for Freightos applications",
   "main": "./dist/cjs/index.js",
@@ -18,6 +18,7 @@
   "files": [
     "dist",
     "tokens.css",
+    "guidelines",
     "README.md",
     "LICENSE"
   ],

package/tokens.css

@@ -385,3 +385,25 @@
 @utility text-fds-h6 {
   font-size: var(--text-fds-h6);
 }
+
+/* Scoped preflight for FreightWind components.
+   Apply to native form elements (<button>, <input>, <textarea>, <select>)
+   so components work without global Tailwind preflight. */
+@utility fw-base {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+  border: 0 solid var(--border, currentColor);
+  font: inherit;
+  font-feature-settings: inherit;
+  font-variation-settings: inherit;
+  letter-spacing: inherit;
+  color: inherit;
+  background-color: transparent;
+  border-radius: 0;
+  line-height: inherit;
+  -webkit-appearance: none;
+  appearance: none;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}