@freightos/freightwind 2.1.2 → 2.1.4

package/dist/esm/lib/use-stable-id.js

@@ -1,6 +1,5 @@
 import * as React from 'react';
-let counter = 0;
 export function useStableId(prefix = 'fw') {
-    const [id] = React.useState(() => `${prefix}-${++counter}`);
-    return id;
+    const id = React.useId();
+    return `${prefix}${id}`;
 }

package/dist/types/components/chip.d.ts

@@ -10,7 +10,7 @@ export interface ChipProps {
     children?: string;
 }
 declare const chipVariants: (props?: ({
-    variant?: "default" | "info" | "success" | "warning" | "error" | "neutral" | "highlight" | "notice" | null | undefined;
+    variant?: "default" | "success" | "error" | "info" | "warning" | "neutral" | "highlight" | "notice" | null | undefined;
 } & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;
 declare function Chip({ variant, icon, closable, onClose, badge, children, }: ChipProps): import("react/jsx-runtime").JSX.Element | null;
 export { Chip, chipVariants };

package/dist/types/components/upload.d.ts

@@ -0,0 +1,66 @@
+import { type HTMLAttributes } from 'react';
+import { type VariantProps } from 'class-variance-authority';
+export type UploadVariant = 'rectangle' | 'square';
+export type ForbiddenReason = 'multiple' | 'type' | 'size' | 'extension' | 'custom';
+export type UploadFile = File | {
+    name: string;
+};
+export type UploadTranslator = (key: string) => string;
+declare const uploadVariants: (props?: ({
+    variant?: "square" | "rectangle" | null | undefined;
+    state?: "default" | "disabled" | "forbidden" | "uploading" | "uploading-spinner" | "success" | "error" | null | undefined;
+} & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;
+export interface UploadProps extends Omit<HTMLAttributes<HTMLLabelElement>, 'onChange'>, VariantProps<typeof uploadVariants> {
+    /** Test automation identifier. Rendered as `data-test-id` on the root and propagated to inner DOM nodes. */
+    dataTestId: string;
+    /** Layout variant. */
+    variant?: UploadVariant;
+    /** Single associated file (controlled). Pass `{ name: string }` for SSR display-only previews. */
+    value?: UploadFile | null;
+    /** Multiple associated files (controlled). Overrides `value` when provided. */
+    files?: UploadFile[];
+    /** Max number of files allowed. Omit or set to 1 for single-file mode. Exceeding this → forbidden. */
+    maxFiles?: number;
+    /** MIME types / extensions accepted. Pass an array, e.g. `['application/pdf', '.png']`. */
+    accept?: string[];
+    /** Max bytes per file. Exceeding this → forbidden. */
+    maxSize?: number;
+    /** Drives the error visual state (red frame + red icon). */
+    isError?: boolean;
+    /** Disables the surface (gray border, no interaction, no remove allowed). */
+    isDisabled?: boolean;
+    /** Stretch the surface to fill its parent's width and height. */
+    isFillContainer?: boolean;
+    /** Override copy per state. Pass any subset; falls back to defaults. */
+    labels?: Partial<{
+        idleTitle: string;
+        idleSubtitle: string;
+        idleCompact: string;
+        uploading: string;
+        forbidden: Partial<Record<ForbiddenReason, {
+            title: string;
+            subtitle: string;
+            compact?: string;
+        }>>;
+    }>;
+    /** Optional translation function for all built-in copy. Defaults to identity. */
+    t?: UploadTranslator;
+    /** Fires when one or more files are selected or dropped. The component flips to `uploading` after this fires; call `setIsUploading(false)` when your async upload completes. Pass an optional `progress` value (0–1) to drive the determinate progress bar; omit it for the indeterminate animation. */
+    onUpload?: (files: File[], setIsUploading: (v: boolean, progress?: number) => void) => void;
+    /** Fires when the trash button is clicked. Removes ALL files. */
+    onRemove?: () => void;
+    /** Fires when an invalid drag/drop is detected. */
+    onForbidden?: (reason: ForbiddenReason) => void;
+    /** A11y label override for the surface. */
+    ariaLabel?: string;
+    /** Seed the internal uploading state on mount. Useful for static demos and Storybook. */
+    defaultUploading?: boolean;
+    /** Seed the initial progress value (0–1) when defaultUploading is true. Disables the indeterminate animation and shows a static determinate bar. */
+    defaultUploadProgress?: number;
+    /** Seed the forbidden state on mount with a specific reason. Useful for static demos and Storybook. */
+    defaultForbidden?: ForbiddenReason;
+    /** Controls the uploading display: 'progress' = text + progress bar (default); 'spinner' = 32×32 spinner only (no text — enforced for square too). */
+    uploadingStyle?: 'progress' | 'spinner';
+}
+export declare const Upload: import("react").ForwardRefExoticComponent<UploadProps & import("react").RefAttributes<HTMLLabelElement>>;
+export { uploadVariants };

package/dist/types/index.d.ts

@@ -2,3 +2,5 @@ export { cn } from './lib/utils';
 export { useStableId } from './lib/use-stable-id';
 export { iconMap, renderInputIcon } from './lib/icon-utils';
 export type { IconName, InputShellSize } from './lib/icon-utils';
+export { Upload, uploadVariants } from './components/upload';
+export type { UploadProps, UploadVariant, UploadFile, ForbiddenReason, UploadTranslator } from './components/upload';

package/dist/types/lib/file-extensions.d.ts

@@ -0,0 +1,52 @@
+/**
+ * MIME-type → extensions map sourced from the IANA / Apache / Nginx MIME database
+ * (https://github.com/jshttp/mime-db). Keys are canonical MIME types
+ * (e.g. `image/aces`); values are the extensions that legitimately produce that
+ * type, without a leading dot and in lowercase.
+ *
+ * Used to validate uploaded files: reject when the browser-reported `File.type`
+ * is unknown, **and** cross-check that the filename's extension matches the set
+ * registered for that type. This catches "extension spoofing" — e.g. a `.exe`
+ * renamed to `.jpg` will report `application/x-msdownload` (or empty), which
+ * does not list `jpg`, so it fails validation.
+ */
+export declare const VALID_MIME_TYPES: Readonly<Record<string, readonly string[]>>;
+/**
+ * Flat set of every extension known to {@link VALID_MIME_TYPES}, used by the
+ * extension-only fast path ({@link hasValidExtension}). Derived once at module
+ * load — kept in sync with the map automatically.
+ */
+export declare const VALID_FILE_EXTENSIONS: ReadonlySet<string>;
+/**
+ * Normalize a filename or raw extension to a lowercase no-dot extension token.
+ * Returns null if no extension is present.
+ */
+export declare function normalizeExtension(input: string): string | null;
+/**
+ * Returns true when the given filename ends in a recognized extension.
+ * Files with no extension, or extensions that aren't in {@link VALID_FILE_EXTENSIONS},
+ * are rejected as "fake" / nonsense.
+ *
+ * Prefer {@link validateFileType} when a `File` object is available — it catches
+ * extension spoofing that this function cannot.
+ */
+export declare function hasValidExtension(filename: string): boolean;
+/**
+ * Strict file validation: the browser-reported MIME type must be known, AND the
+ * filename's extension must be one of the extensions registered for that type.
+ *
+ * Rejects:
+ *  - files with no extension
+ *  - files whose `type` is empty or unknown to {@link VALID_MIME_TYPES}
+ *  - files whose extension does not match the registered list for `file.type`
+ *    (extension-spoofing guard, e.g. `.exe` renamed to `.jpg`)
+ *
+ * `file.type` comparison is case-insensitive; some browsers lowercase but a few
+ * legacy ones don't.
+ */
+export declare function validateFileType(file: File): boolean;
+/**
+ * Look up every MIME type that legitimately produces the given extension.
+ * Useful for `accept`-attribute construction or reverse diagnostics.
+ */
+export declare function getMimeTypesForExtension(extension: string): readonly string[];

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