@freightos/freightwind 2.1.1 → 2.1.3-host-isolation.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 Freightos
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2024 Freightos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,28 +1,56 @@
-# @freightos/freightwind
-
-FreightWind Design System — React UI components for Freightos applications.
-
-## Installation
-
-```bash
-npm install @freightos/freightwind @freightos/freightwind/icons
-```
-
-## Usage
-
-```tsx
-import { Button, Alert, Badge } from '@freightos/freightwind';
-import '@freightos/freightwind/tokens.css';
-```
-
-Components require Tailwind CSS v4 with the FDS design tokens loaded via `tokens.css`.
-
-## Peer Dependencies
-
-- `react` >= 18
-- `react-dom` >= 18
-- `@freightos/freightwind/icons` >= 1.0.0
-
-## License
-
-MIT
+# @freightos/freightwind
+
+FreightWind Design System — React UI components for Freightos applications.
+
+## Installation
+
+```bash
+npm install @freightos/freightwind @freightos/freightwind/icons
+```
+
+## Usage
+
+```tsx
+import { Button, Alert, Badge } from '@freightos/freightwind';
+import '@freightos/freightwind/tokens.css';
+```
+
+Components require Tailwind CSS v4 with the FDS design tokens loaded via `tokens.css`.
+
+## Host isolation (WebCargo)
+
+When mounting FreightWind inside the WebCargo host, also import the WebCargo
+isolation sheet and wrap your App in a `.fw-root` element:
+
+```tsx
+import '@freightos/freightwind/tokens.css';
+import '@freightos/freightwind/host-isolation/webcargo.css';
+
+<div className="fw-root">
+  <App />
+</div>
+```
+
+The sheet ports Tailwind's standard Preflight scoped to `.fw-root` via
+`:where()` (zero added specificity), plus a focus-bleed cancellation keyed
+on the `.fw-base` per-element marker so it covers FW components rendered
+inside Radix portals (Dialog / Popover / Tooltip / DropdownMenu / Select).
+It exists solely to neutralize WebCargo's Bootstrap-style host CSS that
+targets bare element selectors (`h1-h6 { margin-bottom: .5rem }`,
+`button { border-radius: 0 }`, `button:focus { outline: 5px auto … }`, …) —
+it does NOT impose FW-specific styling, so it never drifts from FW design
+tokens.
+
+Skip this file when consuming FreightWind in a clean host (Vite playground,
+greenfield Next.js apps, partner sites without Bootstrap) — there is no host
+CSS to fight there.
+
+## Peer Dependencies
+
+- `react` >= 18
+- `react-dom` >= 18
+- `@freightos/freightwind/icons` >= 1.0.0
+
+## License
+
+MIT

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: "xs", 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.IconClear, { size: "xxs" }) }))] }));
+    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) && '!ps-0.5'), children: [badge !== undefined && (typeof badge === 'string' ? badge.length > 0 : badge > 0) && ((0, jsx_runtime_1.jsx)("span", { className: (0, utils_1.cn)('me-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: "xs", className: children ? 'me-fds-sm' : '' }), children, closable && ((0, jsx_runtime_1.jsx)("button", { type: "button", onClick: handleClose, "aria-label": "Remove", className: "fw-base ms-fds-sm inline-flex cursor-pointer items-center hover:opacity-70", children: (0, jsx_runtime_1.jsx)(icons_1.IconClear, { size: "xxs" }) }))] }));
 }

package/dist/cjs/lib/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderInputIcon = exports.iconMap = exports.useStableId = exports.cn = void 0;
+var utils_1 = require("./utils");
+Object.defineProperty(exports, "cn", { enumerable: true, get: function () { return utils_1.cn; } });
+var use_stable_id_1 = require("./use-stable-id");
+Object.defineProperty(exports, "useStableId", { enumerable: true, get: function () { return use_stable_id_1.useStableId; } });
+var icon_utils_1 = require("./icon-utils");
+Object.defineProperty(exports, "iconMap", { enumerable: true, get: function () { return icon_utils_1.iconMap; } });
+Object.defineProperty(exports, "renderInputIcon", { enumerable: true, get: function () { return icon_utils_1.renderInputIcon; } });

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: "xs", 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(IconClear, { size: "xxs" }) }))] }));
+    return (_jsxs("div", { className: cn(chipVariants({ variant }), iconOnly && 'justify-center', badge !== undefined && (typeof badge === 'string' ? badge.length > 0 : badge > 0) && '!ps-0.5'), children: [badge !== undefined && (typeof badge === 'string' ? badge.length > 0 : badge > 0) && (_jsx("span", { className: cn('me-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: "xs", className: children ? 'me-fds-sm' : '' }), children, closable && (_jsx("button", { type: "button", onClick: handleClose, "aria-label": "Remove", className: "fw-base ms-fds-sm inline-flex cursor-pointer items-center hover:opacity-70", children: _jsx(IconClear, { size: "xxs" }) }))] }));
 }
 export { Chip, chipVariants };

package/dist/esm/lib/index.js

@@ -0,0 +1,3 @@
+export { cn } from './utils';
+export { useStableId } from './use-stable-id';
+export { iconMap, renderInputIcon } from './icon-utils';

package/dist/types/lib/index.d.ts

@@ -0,0 +1,4 @@
+export { cn } from './utils';
+export { useStableId } from './use-stable-id';
+export { iconMap, renderInputIcon } from './icon-utils';
+export type { IconName, InputShellSize } from './icon-utils';

package/guidelines/Guidelines.md

@@ -1,233 +1,233 @@
-# 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/freightwind/icons tailwindcss @tailwindcss/vite
-```
-
-`@freightos/freightwind/icons` is a required peer dependency that provides all iconography. Tailwind CSS v4 is required for component styling.
-
-### Step 2 — Configure Tailwind CSS v4
-
-FreightWind requires Tailwind CSS v4. Set it up with your bundler:
-
-**Vite** — add the Tailwind plugin to `vite.config.ts`:
-
-```ts
-import tailwindcss from '@tailwindcss/vite';
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
-
-export default defineConfig({
-  plugins: [react(), tailwindcss()],
-});
-```
-
-### Step 3 — Set up your global CSS file
-
-**CRITICAL**: Your main CSS file must import Tailwind AND FreightWind tokens in the correct order. The tokens.css file uses Tailwind v4's `@theme inline` directive to register color utilities (like `bg-fds-blue-30`, `text-fds-gray-80`, etc.) — this ONLY works when imported inside a CSS file that Tailwind processes.
-
-Create or update your main CSS file (e.g. `src/index.css` or `src/styles/globals.css`):
-
-```css
-/* Step A: Import Tailwind CSS — this MUST come first */
-@import "tailwindcss";
-
-/* Step B: Import FreightWind tokens — MUST be in this same CSS file, AFTER tailwindcss.
-   This registers all FDS color utilities (bg-fds-blue-30, text-fds-gray-80, etc.),
-   spacing tokens, typography tokens, and custom utilities used by components.
-
-   DO NOT import this as a <link> tag in HTML — it must be processed by Tailwind's
-   CSS engine for @theme inline to work. */
-@import "@freightos/freightwind/tokens.css";
-
-/* Step C: Global base styles — REQUIRED for components to render correctly */
-* {
-  -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;
-}
-```
-
-**IMPORTANT NOTES:**
-- `@import "@freightos/freightwind/tokens.css"` MUST be inside the same CSS file as `@import "tailwindcss"` — never in a separate file or `<link>` tag
-- The import order matters: `tailwindcss` first, then `tokens.css`
-- If tokens are imported separately or in the wrong order, Tailwind utility classes like `bg-fds-purple-2`, `bg-fds-gray-20`, `text-fds-blue-30`, etc. will NOT work and components will have missing styles
-
-### Step 4 — Load the Open Sans font
-
-FreightWind uses **Open Sans** as its font family. Load weights 400, 600, and 700 from Google Fonts.
-
-**Option A — In your HTML `<head>` (simplest):**
-
-```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 5 — Import and use components
-
-```tsx
-import { Button, Alert, Checkbox } from '@freightos/freightwind';
-import { IconSearch } from '@freightos/freightwind/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');
-```
-
-## Complete minimal example
-
-Here is a full working `src/index.css`:
-
-```css
-@import "tailwindcss";
-@import "@freightos/freightwind/tokens.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;
-  line-height: 1.5;
-}
-```
-
-And a full working `src/App.tsx`:
-
-```tsx
-import { Button, Alert, Chip, Switch, Checkbox } from '@freightos/freightwind';
-import { IconSearch } from '@freightos/freightwind/icons';
-
-function App() {
-  return (
-    <div className="p-fds-xl">
-      <h1 className="text-fds-h3 font-fds-bold leading-fds-title mb-fds-lg">My App</h1>
-      <Alert variant="info" message="Welcome to the app!" />
-      <div className="mt-fds-lg flex gap-fds-sm">
-        <Button variant="default">Primary</Button>
-        <Button variant="secondary">Secondary</Button>
-        <Button icon="search" tooltip="Search" />
-      </div>
-      <div className="mt-fds-lg flex gap-fds-md items-center">
-        <Chip variant="success">Active</Chip>
-        <Switch>Enable notifications</Switch>
-        <Checkbox>Accept terms</Checkbox>
-      </div>
-    </div>
-  );
-}
-```
-
-## Troubleshooting
-
-### Tailwind utility classes not working (e.g. `bg-fds-purple-2` has no effect)
-
-This means `tokens.css` is not being processed by Tailwind. Make sure:
-1. `@import "@freightos/freightwind/tokens.css"` is in the SAME CSS file as `@import "tailwindcss"`
-2. It comes AFTER the tailwindcss import
-3. It is NOT loaded via a `<link>` tag — it must be in CSS `@import` so Tailwind processes the `@theme inline` block
-
-### Colors like `--ground`, `--foreground`, `--card` are undefined
-
-These CSS variables are defined in the `:root` block inside `tokens.css`. Make sure `tokens.css` is imported.
-
-### Font looks wrong
-
-Make sure Open Sans is loaded (Step 4) and the body `font-family` is set (Step 3C).
-
-### Text rendering looks rough or inconsistent
-
-Add global font smoothing (Step 3C):
-```css
-* {
-  -webkit-font-smoothing: antialiased;
-  -moz-osx-font-smoothing: grayscale;
-}
-```
-
-## 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
+# 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/freightwind/icons tailwindcss @tailwindcss/vite
+```
+
+`@freightos/freightwind/icons` is a required peer dependency that provides all iconography. Tailwind CSS v4 is required for component styling.
+
+### Step 2 — Configure Tailwind CSS v4
+
+FreightWind requires Tailwind CSS v4. Set it up with your bundler:
+
+**Vite** — add the Tailwind plugin to `vite.config.ts`:
+
+```ts
+import tailwindcss from '@tailwindcss/vite';
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+});
+```
+
+### Step 3 — Set up your global CSS file
+
+**CRITICAL**: Your main CSS file must import Tailwind AND FreightWind tokens in the correct order. The tokens.css file uses Tailwind v4's `@theme inline` directive to register color utilities (like `bg-fds-blue-30`, `text-fds-gray-80`, etc.) — this ONLY works when imported inside a CSS file that Tailwind processes.
+
+Create or update your main CSS file (e.g. `src/index.css` or `src/styles/globals.css`):
+
+```css
+/* Step A: Import Tailwind CSS — this MUST come first */
+@import "tailwindcss";
+
+/* Step B: Import FreightWind tokens — MUST be in this same CSS file, AFTER tailwindcss.
+   This registers all FDS color utilities (bg-fds-blue-30, text-fds-gray-80, etc.),
+   spacing tokens, typography tokens, and custom utilities used by components.
+
+   DO NOT import this as a <link> tag in HTML — it must be processed by Tailwind's
+   CSS engine for @theme inline to work. */
+@import "@freightos/freightwind/tokens.css";
+
+/* Step C: Global base styles — REQUIRED for components to render correctly */
+* {
+  -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;
+}
+```
+
+**IMPORTANT NOTES:**
+- `@import "@freightos/freightwind/tokens.css"` MUST be inside the same CSS file as `@import "tailwindcss"` — never in a separate file or `<link>` tag
+- The import order matters: `tailwindcss` first, then `tokens.css`
+- If tokens are imported separately or in the wrong order, Tailwind utility classes like `bg-fds-purple-2`, `bg-fds-gray-20`, `text-fds-blue-30`, etc. will NOT work and components will have missing styles
+
+### Step 4 — Load the Open Sans font
+
+FreightWind uses **Open Sans** as its font family. Load weights 400, 600, and 700 from Google Fonts.
+
+**Option A — In your HTML `<head>` (simplest):**
+
+```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 5 — Import and use components
+
+```tsx
+import { Button, Alert, Checkbox } from '@freightos/freightwind';
+import { IconSearch } from '@freightos/freightwind/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');
+```
+
+## Complete minimal example
+
+Here is a full working `src/index.css`:
+
+```css
+@import "tailwindcss";
+@import "@freightos/freightwind/tokens.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;
+  line-height: 1.5;
+}
+```
+
+And a full working `src/App.tsx`:
+
+```tsx
+import { Button, Alert, Chip, Switch, Checkbox } from '@freightos/freightwind';
+import { IconSearch } from '@freightos/freightwind/icons';
+
+function App() {
+  return (
+    <div className="p-fds-xl">
+      <h1 className="text-fds-h3 font-fds-bold leading-fds-title mb-fds-lg">My App</h1>
+      <Alert variant="info" message="Welcome to the app!" />
+      <div className="mt-fds-lg flex gap-fds-sm">
+        <Button variant="default">Primary</Button>
+        <Button variant="secondary">Secondary</Button>
+        <Button icon="search" tooltip="Search" />
+      </div>
+      <div className="mt-fds-lg flex gap-fds-md items-center">
+        <Chip variant="success">Active</Chip>
+        <Switch>Enable notifications</Switch>
+        <Checkbox>Accept terms</Checkbox>
+      </div>
+    </div>
+  );
+}
+```
+
+## Troubleshooting
+
+### Tailwind utility classes not working (e.g. `bg-fds-purple-2` has no effect)
+
+This means `tokens.css` is not being processed by Tailwind. Make sure:
+1. `@import "@freightos/freightwind/tokens.css"` is in the SAME CSS file as `@import "tailwindcss"`
+2. It comes AFTER the tailwindcss import
+3. It is NOT loaded via a `<link>` tag — it must be in CSS `@import` so Tailwind processes the `@theme inline` block
+
+### Colors like `--ground`, `--foreground`, `--card` are undefined
+
+These CSS variables are defined in the `:root` block inside `tokens.css`. Make sure `tokens.css` is imported.
+
+### Font looks wrong
+
+Make sure Open Sans is loaded (Step 4) and the body `font-family` is set (Step 3C).
+
+### Text rendering looks rough or inconsistent
+
+Add global font smoothing (Step 3C):
+```css
+* {
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+```
+
+## 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