@freightos/freightwind 1.1.1 → 1.1.2

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 +99 -12
  2. package/guidelines/design-tokens/typography.md +37 -0
  3. package/package.json +1 -1
package/guidelines/Guidelines.md CHANGED
@@ -2,33 +2,118 @@
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
13
+ ```
14
+
15
+ `@freightos/icons` is a required peer dependency that provides all iconography.
16
+
17
+ ### Step 2 — Load the Open Sans font
18
+
19
+ FreightWind uses **Open Sans** as its font family. Load it from Google Fonts.
20
+
21
+ **Option A — In your HTML `<head>`:**
22
+
23
+ ```html
24
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
25
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
26
+ <link href="https://fonts.googleapis.com/css2?family=Open+Sans:wght@400;600;700&display=swap" rel="stylesheet" />
27
+ ```
28
+
29
+ **Option B — In Next.js with `next/font`:**
30
+
31
+ ```tsx
32
+ import { Open_Sans } from 'next/font/google';
33
+
34
+ const openSans = Open_Sans({
35
+ subsets: ['latin'],
36
+ weight: ['400', '600', '700'],
37
+ variable: '--font-open-sans',
38
+ });
39
+
40
+ // Apply to <html> or <body>:
41
+ <html className={openSans.variable}>
42
+ ```
43
+
44
+ Then in your CSS, override the font-sans variable:
45
+
46
+ ```css
47
+ @theme inline {
48
+ --font-sans: var(--font-open-sans), 'Open Sans', ui-sans-serif, system-ui, sans-serif;
49
+ }
50
+ ```
51
+
52
+ ### Step 3 — Import tokens CSS
53
+
54
+ Import the FreightWind tokens stylesheet in your global CSS file. This provides all design tokens, color variables, and custom utilities:
10
55
 
11
56
  ```css
12
57
  @import "@freightos/freightwind/tokens.css";
13
58
  ```
14
59
 
15
- 2. **Components** — import components from the package:
60
+ ### Step 4 — Set up global body styles
61
+
62
+ Add these base styles in your global CSS. These are REQUIRED for components to render correctly:
63
+
64
+ ```css
65
+ * {
66
+ -webkit-font-smoothing: antialiased;
67
+ -moz-osx-font-smoothing: grayscale;
68
+ }
69
+
70
+ body {
71
+ background-color: var(--ground);
72
+ color: var(--foreground);
73
+ font-family: 'Open Sans', ui-sans-serif, system-ui, -apple-system, sans-serif;
74
+ font-size: 0.875rem; /* 14px — FDS base font size */
75
+ line-height: 1.5;
76
+ }
77
+ ```
78
+
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
16
84
 
17
85
  ```tsx
18
86
  import { Button, Alert, Checkbox } from '@freightos/freightwind';
87
+ import { IconSearch } from '@freightos/icons';
88
+
89
+ <Button variant="default" size="md">Submit</Button>
90
+ <Alert variant="info" message="Shipment updated." />
91
+ <Checkbox>Accept terms</Checkbox>
19
92
  ```
20
93
 
21
- 3. **Icons** — icons come from the `@freightos/icons` peer dependency:
94
+ ### Step 6 — Toast notifications (optional)
95
+
96
+ If using the `message` toast API, wrap your app with `MessageProvider`:
22
97
 
23
98
  ```tsx
24
- import { IconSearch, IconClose, IconUser } from '@freightos/icons';
25
- ```
99
+ import { MessageProvider, message } from '@freightos/freightwind';
100
+
101
+ // In your root layout:
102
+ <MessageProvider />
26
103
 
27
- Components that accept an `icon` prop use kebab-case icon names (e.g. `icon="search"`, `icon="close"`), not direct icon imports.
104
+ // Anywhere in your app:
105
+ message.success('Saved successfully');
106
+ ```
28
107
 
29
108
  ## Tailwind CSS requirement
30
109
 
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.
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.
111
+
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.
113
+
114
+ ## Dark mode
115
+
116
+ 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
117
 
33
118
  ## Available components
34
119
 
@@ -42,9 +127,9 @@ See `overview-icons.md` for details on the icon system.
42
127
 
43
128
  FreightWind uses a custom token system instead of Tailwind defaults:
44
129
 
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
130
+ - **Colors**: `design-tokens/colors.md` — semantic color palette (blue, red, green, yellow, gray, purple)
131
+ - **Typography**: `design-tokens/typography.md` — font family, sizes, weights, and line heights
132
+ - **Spacing**: `design-tokens/spacing.md` — consistent spacing scale
48
133
 
49
134
  ## Key conventions
50
135
 
@@ -52,3 +137,5 @@ FreightWind uses a custom token system instead of Tailwind defaults:
52
137
  - All components support both controlled and uncontrolled usage patterns
53
138
  - Components with `icon` props accept kebab-case icon names: `"search"`, `"close"`, `"user"`, `"risk"`, etc.
54
139
  - Use `cn()` utility (exported from the package) for className merging
140
+ - The page canvas background should be `bg-ground` (#f6f6f6), not white
141
+ - 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.2",
4
4
  "private": false,
5
5
  "description": "FreightWind Design System — React UI components for Freightos applications",
6
6
  "main": "./dist/cjs/index.js",