@freightos/freightwind 1.1.2 → 1.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/guidelines/Guidelines.md +125 -33
  2. package/package.json +1 -1
package/guidelines/Guidelines.md CHANGED
@@ -9,16 +9,70 @@ Follow ALL steps below to properly set up FreightWind in a React project.
9
9
  ### Step 1 — Install dependencies
10
10
 
11
11
  ```bash
12
- npm install @freightos/freightwind @freightos/icons
12
+ npm install @freightos/freightwind @freightos/icons tailwindcss @tailwindcss/vite
13
13
  ```
14
14
 
15
- `@freightos/icons` is a required peer dependency that provides all iconography.
15
+ `@freightos/icons` is a required peer dependency that provides all iconography. Tailwind CSS v4 is required for component styling.
16
16
 
17
- ### Step 2 — Load the Open Sans font
17
+ ### Step 2 — Configure Tailwind CSS v4
18
18
 
19
- FreightWind uses **Open Sans** as its font family. Load it from Google Fonts.
19
+ FreightWind requires Tailwind CSS v4. Set it up with your bundler:
20
20
 
21
- **Option A — In your HTML `<head>`:**
21
+ **Vite** — add the Tailwind plugin to `vite.config.ts`:
22
+
23
+ ```ts
24
+ import tailwindcss from '@tailwindcss/vite';
25
+ import { defineConfig } from 'vite';
26
+ import react from '@vitejs/plugin-react';
27
+
28
+ export default defineConfig({
29
+ plugins: [react(), tailwindcss()],
30
+ });
31
+ ```
32
+
33
+ ### Step 3 — Set up your global CSS file
34
+
35
+ **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.
36
+
37
+ Create or update your main CSS file (e.g. `src/index.css` or `src/styles/globals.css`):
38
+
39
+ ```css
40
+ /* Step A: Import Tailwind CSS — this MUST come first */
41
+ @import "tailwindcss";
42
+
43
+ /* Step B: Import FreightWind tokens — MUST be in this same CSS file, AFTER tailwindcss.
44
+ This registers all FDS color utilities (bg-fds-blue-30, text-fds-gray-80, etc.),
45
+ spacing tokens, typography tokens, and custom utilities used by components.
46
+
47
+ DO NOT import this as a <link> tag in HTML — it must be processed by Tailwind's
48
+ CSS engine for @theme inline to work. */
49
+ @import "@freightos/freightwind/tokens.css";
50
+
51
+ /* Step C: Global base styles — REQUIRED for components to render correctly */
52
+ * {
53
+ -webkit-font-smoothing: antialiased;
54
+ -moz-osx-font-smoothing: grayscale;
55
+ }
56
+
57
+ body {
58
+ background-color: var(--ground);
59
+ color: var(--foreground);
60
+ font-family: 'Open Sans', ui-sans-serif, system-ui, -apple-system, sans-serif;
61
+ font-size: 0.875rem; /* 14px — FDS base font size */
62
+ line-height: 1.5;
63
+ }
64
+ ```
65
+
66
+ **IMPORTANT NOTES:**
67
+ - `@import "@freightos/freightwind/tokens.css"` MUST be inside the same CSS file as `@import "tailwindcss"` — never in a separate file or `<link>` tag
68
+ - The import order matters: `tailwindcss` first, then `tokens.css`
69
+ - 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
70
+
71
+ ### Step 4 — Load the Open Sans font
72
+
73
+ FreightWind uses **Open Sans** as its font family. Load weights 400, 600, and 700 from Google Fonts.
74
+
75
+ **Option A — In your HTML `<head>` (simplest):**
22
76
 
23
77
  ```html
24
78
  <link rel="preconnect" href="https://fonts.googleapis.com" />
@@ -49,19 +103,39 @@ Then in your CSS, override the font-sans variable:
49
103
  }
50
104
  ```
51
105
 
52
- ### Step 3 — Import tokens CSS
106
+ ### Step 5 — Import and use components
53
107
 
54
- Import the FreightWind tokens stylesheet in your global CSS file. This provides all design tokens, color variables, and custom utilities:
108
+ ```tsx
109
+ import { Button, Alert, Checkbox } from '@freightos/freightwind';
110
+ import { IconSearch } from '@freightos/icons';
55
111
 
56
- ```css
57
- @import "@freightos/freightwind/tokens.css";
112
+ <Button variant="default" size="md">Submit</Button>
113
+ <Alert variant="info" message="Shipment updated." />
114
+ <Checkbox>Accept terms</Checkbox>
115
+ ```
116
+
117
+ ### Step 6 — Toast notifications (optional)
118
+
119
+ If using the `message` toast API, wrap your app with `MessageProvider`:
120
+
121
+ ```tsx
122
+ import { MessageProvider, message } from '@freightos/freightwind';
123
+
124
+ // In your root layout:
125
+ <MessageProvider />
126
+
127
+ // Anywhere in your app:
128
+ message.success('Saved successfully');
58
129
  ```
59
130
 
60
- ### Step 4 — Set up global body styles
131
+ ## Complete minimal example
61
132
 
62
- Add these base styles in your global CSS. These are REQUIRED for components to render correctly:
133
+ Here is a full working `src/index.css`:
63
134
 
64
135
  ```css
136
+ @import "tailwindcss";
137
+ @import "@freightos/freightwind/tokens.css";
138
+
65
139
  * {
66
140
  -webkit-font-smoothing: antialiased;
67
141
  -moz-osx-font-smoothing: grayscale;
@@ -71,45 +145,63 @@ body {
71
145
  background-color: var(--ground);
72
146
  color: var(--foreground);
73
147
  font-family: 'Open Sans', ui-sans-serif, system-ui, -apple-system, sans-serif;
74
- font-size: 0.875rem; /* 14px — FDS base font size */
148
+ font-size: 0.875rem;
75
149
  line-height: 1.5;
76
150
  }
77
151
  ```
78
152
 
79
- The `--ground` color is `#f6f6f6` (light gray page canvas). The `--foreground` color is `#3b3f4b` (dark gray text).
80
-
81
- Font smoothing (`antialiased`) MUST be applied globally — without it, text will look inconsistent across browsers.
82
-
83
- ### Step 5 — Import and use components
153
+ And a full working `src/App.tsx`:
84
154
 
85
155
  ```tsx
86
- import { Button, Alert, Checkbox } from '@freightos/freightwind';
156
+ import { Button, Alert, Chip, Switch, Checkbox } from '@freightos/freightwind';
87
157
  import { IconSearch } from '@freightos/icons';
88
158
 
89
- <Button variant="default" size="md">Submit</Button>
90
- <Alert variant="info" message="Shipment updated." />
91
- <Checkbox>Accept terms</Checkbox>
159
+ function App() {
160
+ return (
161
+ <div className="p-fds-xl">
162
+ <h1 className="text-fds-h3 font-fds-bold leading-fds-title mb-fds-lg">My App</h1>
163
+ <Alert variant="info" message="Welcome to the app!" />
164
+ <div className="mt-fds-lg flex gap-fds-sm">
165
+ <Button variant="default">Primary</Button>
166
+ <Button variant="secondary">Secondary</Button>
167
+ <Button icon="search" tooltip="Search" />
168
+ </div>
169
+ <div className="mt-fds-lg flex gap-fds-md items-center">
170
+ <Chip variant="success">Active</Chip>
171
+ <Switch>Enable notifications</Switch>
172
+ <Checkbox>Accept terms</Checkbox>
173
+ </div>
174
+ </div>
175
+ );
176
+ }
92
177
  ```
93
178
 
94
- ### Step 6 — Toast notifications (optional)
179
+ ## Troubleshooting
95
180
 
96
- If using the `message` toast API, wrap your app with `MessageProvider`:
181
+ ### Tailwind utility classes not working (e.g. `bg-fds-purple-2` has no effect)
97
182
 
98
- ```tsx
99
- import { MessageProvider, message } from '@freightos/freightwind';
183
+ This means `tokens.css` is not being processed by Tailwind. Make sure:
184
+ 1. `@import "@freightos/freightwind/tokens.css"` is in the SAME CSS file as `@import "tailwindcss"`
185
+ 2. It comes AFTER the tailwindcss import
186
+ 3. It is NOT loaded via a `<link>` tag — it must be in CSS `@import` so Tailwind processes the `@theme inline` block
100
187
 
101
- // In your root layout:
102
- <MessageProvider />
188
+ ### Colors like `--ground`, `--foreground`, `--card` are undefined
103
189
 
104
- // Anywhere in your app:
105
- message.success('Saved successfully');
106
- ```
190
+ These CSS variables are defined in the `:root` block inside `tokens.css`. Make sure `tokens.css` is imported.
107
191
 
108
- ## Tailwind CSS requirement
192
+ ### Font looks wrong
109
193
 
110
- 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.
194
+ Make sure Open Sans is loaded (Step 4) and the body `font-family` is set (Step 3C).
111
195
 
112
- 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.
196
+ ### Text rendering looks rough or inconsistent
197
+
198
+ Add global font smoothing (Step 3C):
199
+ ```css
200
+ * {
201
+ -webkit-font-smoothing: antialiased;
202
+ -moz-osx-font-smoothing: grayscale;
203
+ }
204
+ ```
113
205
 
114
206
  ## Dark mode
115
207
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@freightos/freightwind",
3
- "version": "1.1.2",
3
+ "version": "1.1.3",
4
4
  "private": false,
5
5
  "description": "FreightWind Design System — React UI components for Freightos applications",
6
6
  "main": "./dist/cjs/index.js",