@freightos/freightwind
FreightWind Design System — React UI components for Freightos applications.
Installation
npm install @freightos/freightwind @freightos/freightwind/icons
Usage
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:
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.
MCP Apps (@freightos/freightwind/mcp-app)
Render a FreightWind surface as an interactive card inside AI chats (Claude,
ChatGPT) via the MCP Apps standard. useMcpApp connects to the host, mirrors
its theme (.dark) and language (dir/lang), hands you the tool result,
and stops an older card from sending once a newer one replaces it.
import { useMcpApp } from '@freightos/freightwind/mcp-app';
function Card() {
const { data, isSuperseded, updateModelContext, sendMessage } = useMcpApp<MyData>({
appInfo: { name: 'my-card', version: '1.0.0' },
supersessionChannel: 'my-app:show_thing',
instanceKeyOf: (d) => ({ issuedAt: d.issuedAt, seq: d.seq }),
});
// updateModelContext(text) informs the model quietly; sendMessage(text) posts to the chat.
}
Install the optional peers to use it: @modelcontextprotocol/ext-apps (>= 1.7.5 < 2)
and @modelcontextprotocol/sdk (^1.29). The subpath is ESM-only, like
ext-apps itself. Supersession uses a BroadcastChannel, so a newer card in
another open chat also marks older ones outdated. Full guide: FreightWind
docs → AI → MCP Apps.
Peer Dependencies
react>= 18react-dom>= 18@freightos/freightwind/icons>= 1.0.0@modelcontextprotocol/ext-apps>= 1.7.5 < 2 and@modelcontextprotocol/sdk^1.29 (optional, for/mcp-apponly)
License
MIT