@freightos/freightwind 1.1.1 → 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 (3) hide show
  1. package/guidelines/Guidelines.md +191 -12
  2. package/guidelines/design-tokens/typography.md +37 -0
  3. package/package.json +1 -1
package/guidelines/Guidelines.md CHANGED
@@ -2,33 +2,210 @@
2
2
 
3
3
  FreightWind is the Freightos Design System — a React component library styled with Tailwind CSS v4 and FDS (Freightos Design System) tokens.
4
4
 
5
- ## Setup
5
+ ## Complete Setup
6
6
 
7
- FreightWind requires two imports:
7
+ Follow ALL steps below to properly set up FreightWind in a React project.
8
8
 
9
- 1. **CSS tokens** — import the token stylesheet in your root layout or global CSS:
9
+ ### Step 1 — Install dependencies
10
+
11
+ ```bash
12
+ npm install @freightos/freightwind @freightos/icons tailwindcss @tailwindcss/vite
13
+ ```
14
+
15
+ `@freightos/icons` is a required peer dependency that provides all iconography. Tailwind CSS v4 is required for component styling.
16
+
17
+ ### Step 2 — Configure Tailwind CSS v4
18
+
19
+ FreightWind requires Tailwind CSS v4. Set it up with your bundler:
20
+
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`):
10
38
 
11
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. */
12
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):**
76
+
77
+ ```html
78
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
79
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
80
+ <link href="https://fonts.googleapis.com/css2?family=Open+Sans:wght@400;600;700&display=swap" rel="stylesheet" />
81
+ ```
82
+
83
+ **Option B — In Next.js with `next/font`:**
84
+
85
+ ```tsx
86
+ import { Open_Sans } from 'next/font/google';
87
+
88
+ const openSans = Open_Sans({
89
+ subsets: ['latin'],
90
+ weight: ['400', '600', '700'],
91
+ variable: '--font-open-sans',
92
+ });
93
+
94
+ // Apply to <html> or <body>:
95
+ <html className={openSans.variable}>
96
+ ```
97
+
98
+ Then in your CSS, override the font-sans variable:
99
+
100
+ ```css
101
+ @theme inline {
102
+ --font-sans: var(--font-open-sans), 'Open Sans', ui-sans-serif, system-ui, sans-serif;
103
+ }
13
104
  ```
14
105
 
15
- 2. **Components** — import components from the package:
106
+ ### Step 5 — Import and use components
16
107
 
17
108
  ```tsx
18
109
  import { Button, Alert, Checkbox } from '@freightos/freightwind';
110
+ import { IconSearch } from '@freightos/icons';
111
+
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');
129
+ ```
130
+
131
+ ## Complete minimal example
132
+
133
+ Here is a full working `src/index.css`:
134
+
135
+ ```css
136
+ @import "tailwindcss";
137
+ @import "@freightos/freightwind/tokens.css";
138
+
139
+ * {
140
+ -webkit-font-smoothing: antialiased;
141
+ -moz-osx-font-smoothing: grayscale;
142
+ }
143
+
144
+ body {
145
+ background-color: var(--ground);
146
+ color: var(--foreground);
147
+ font-family: 'Open Sans', ui-sans-serif, system-ui, -apple-system, sans-serif;
148
+ font-size: 0.875rem;
149
+ line-height: 1.5;
150
+ }
19
151
  ```
20
152
 
21
- 3. **Icons** — icons come from the `@freightos/icons` peer dependency:
153
+ And a full working `src/App.tsx`:
22
154
 
23
155
  ```tsx
24
- import { IconSearch, IconClose, IconUser } from '@freightos/icons';
156
+ import { Button, Alert, Chip, Switch, Checkbox } from '@freightos/freightwind';
157
+ import { IconSearch } from '@freightos/icons';
158
+
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
+ }
25
177
  ```
26
178
 
27
- Components that accept an `icon` prop use kebab-case icon names (e.g. `icon="search"`, `icon="close"`), not direct icon imports.
179
+ ## Troubleshooting
180
+
181
+ ### Tailwind utility classes not working (e.g. `bg-fds-purple-2` has no effect)
182
+
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
187
+
188
+ ### Colors like `--ground`, `--foreground`, `--card` are undefined
189
+
190
+ These CSS variables are defined in the `:root` block inside `tokens.css`. Make sure `tokens.css` is imported.
191
+
192
+ ### Font looks wrong
193
+
194
+ Make sure Open Sans is loaded (Step 4) and the body `font-family` is set (Step 3C).
195
+
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
+ ```
28
205
 
29
- ## Tailwind CSS requirement
206
+ ## Dark mode
30
207
 
31
- FreightWind components use Tailwind CSS v4 utility classes. Your project must have Tailwind CSS configured. The `tokens.css` file provides all necessary theme tokens and custom utilities.
208
+ 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.
32
209
 
33
210
  ## Available components
34
211
 
@@ -42,9 +219,9 @@ See `overview-icons.md` for details on the icon system.
42
219
 
43
220
  FreightWind uses a custom token system instead of Tailwind defaults:
44
221
 
45
- - **Colors**: `overview-design-tokens/colors.md` — semantic color palette (blue, red, green, yellow, gray, purple)
46
- - **Typography**: `overview-design-tokens/typography.md` — font sizes, weights, and line heights
47
- - **Spacing**: `overview-design-tokens/spacing.md` — consistent spacing scale
222
+ - **Colors**: `design-tokens/colors.md` — semantic color palette (blue, red, green, yellow, gray, purple)
223
+ - **Typography**: `design-tokens/typography.md` — font family, sizes, weights, and line heights
224
+ - **Spacing**: `design-tokens/spacing.md` — consistent spacing scale
48
225
 
49
226
  ## Key conventions
50
227
 
@@ -52,3 +229,5 @@ FreightWind uses a custom token system instead of Tailwind defaults:
52
229
  - All components support both controlled and uncontrolled usage patterns
53
230
  - Components with `icon` props accept kebab-case icon names: `"search"`, `"close"`, `"user"`, `"risk"`, etc.
54
231
  - Use `cn()` utility (exported from the package) for className merging
232
+ - The page canvas background should be `bg-ground` (#f6f6f6), not white
233
+ - Cards and content areas use `bg-card` (#ffffff) against the ground
package/guidelines/design-tokens/typography.md CHANGED
@@ -2,6 +2,43 @@
2
2
 
3
3
  FreightWind uses FDS typography tokens. Always use these instead of Tailwind default sizes.
4
4
 
5
+ ## Font family
6
+
7
+ FreightWind uses **Open Sans** (Google Fonts). The font must be loaded externally and applied to the body:
8
+
9
+ ```css
10
+ body {
11
+ font-family: 'Open Sans', ui-sans-serif, system-ui, -apple-system, sans-serif;
12
+ }
13
+ ```
14
+
15
+ 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.
16
+
17
+ Required font weights: **400** (regular), **600** (semibold), **700** (bold).
18
+
19
+ ## Font smoothing
20
+
21
+ All text MUST have antialiased font smoothing. Apply globally:
22
+
23
+ ```css
24
+ * {
25
+ -webkit-font-smoothing: antialiased;
26
+ -moz-osx-font-smoothing: grayscale;
27
+ }
28
+ ```
29
+
30
+ Without this, text rendering will look inconsistent across browsers, especially on macOS.
31
+
32
+ ## Base font size
33
+
34
+ The default body font size is **14px** (`0.875rem`), not the browser default 16px:
35
+
36
+ ```css
37
+ body {
38
+ font-size: 0.875rem;
39
+ }
40
+ ```
41
+
5
42
  ## Font sizes
6
43
 
7
44
  | Token | Class | Size | Usage |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@freightos/freightwind",
3
- "version": "1.1.1",
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",