@cboxdk/cbox-ui 0.6.0

package/BRAND.md

@@ -0,0 +1,77 @@
+# Cbox brand guidelines
+
+Living document. Update as the brand matures — but commit the changes here, not in 5 different places across the apps.
+
+## Voice
+
+- **Refined-minimal, not maximalist.** Every Cbox surface should feel like an instrument: precise, quiet, dependable. We're building infrastructure, not entertainment.
+- **Operationally honest.** Status pills say "trial — 7 days left", not "🎉 you're trialing!". Numbers, dates, and amounts are first-class — never hidden behind icons.
+- **Danish-first, English-default.** Customer-facing strings ship in English; Danish localisation is a translation layer, not a separate brand voice.
+
+## Typography
+
+| Slot | Family | Notes |
+|---|---|---|
+| Display + sans | **Plus Jakarta Sans** | Headings, body, UI labels. Loaded via the host app's font setup. |
+| Mono | **JetBrains Mono** | Code, IDs, timestamps, currencies. Surface when precision matters. |
+
+We do **not** use Inter, Roboto, or any system-default font — those are explicitly rejected for being too "generic SaaS". Plus Jakarta Sans is the brand voice in pixels.
+
+## Colour system
+
+Tokens live in [`tokens/cbox.css`](./tokens/cbox.css). Read those — they're the source of truth. Highlights:
+
+- **Primary**: deep blue (`oklch(0.45 0.16 258)` light, `oklch(0.65 0.18 258)` dark). Used for accents, focus rings, the active-tab underline.
+- **Canvas**: a slightly cooler near-white (`oklch(0.975 0.008 250)`) so cards on top feel like they sit *on* a surface, not float in void.
+- **Cards**: pure white in light, `oklch(0.2 0.01 250)` in dark. Subtle 1px border (`--color-border`) and a 1px shadow.
+- **Tones**: success (green), warning (amber), info (cyan-blue), destructive (red). Each has a `-soft` variant for badge backgrounds and a foreground pair.
+
+### Don't
+
+- Mix tones inside a single component — pick one and commit to it.
+- Use full-saturation colours for background fills. The `-soft` variants exist for that.
+- Introduce new colour scales without updating `tokens/cbox.css` — drift kills brand consistency faster than anything else.
+
+## Iconography
+
+- **Lucide** for the standard set (24/16px outline icons).
+- **Custom Cbox icons** (logos, app monograms, brand marks) live in `assets/`. SVG only.
+- Icon size: `h-3.5 w-3.5` for inline tab/menu icons, `h-4 w-4` for buttons, `h-5 w-5` for empty-state heroes.
+
+## Radius
+
+- `--radius: 0.625rem` (10px) for cards + dialogs.
+- `--radius-md: 8px` for buttons + inputs.
+- `--radius-sm: 6px` for badges + small chips.
+
+Uniformity matters more than the exact pixel — **don't round everything**, but never mix sharp corners with our chosen radii in the same component.
+
+## Motion
+
+- **Cubic-bezier(.4, 0, .2, 1)** for state transitions (the default Tailwind `transition`).
+- **150ms** for hover/focus, **200ms** for menu open/close, **300ms** for layout shift.
+- Avoid spring physics, fancy easing curves, or anything that draws attention to motion itself. The user shouldn't notice the animation — they should notice that things feel responsive.
+
+## Layout rhythm
+
+- Top bar: 56px (`h-14`).
+- Sidebar: 240px collapsed, 280px expanded.
+- Page max-width: untyped — pages span the full content area, sections inside use `max-w-*` as needed.
+- Vertical spacing between sections on a page: `space-y-6` (24px).
+- Padding inside `DataPanel`: 20px (`px-5 py-4`).
+
+## Naming
+
+- App keys are short, lowercase, single-word: `id`, `cortex`, `atlas`, `track`.
+- App display names use Title Case: "Cbox · ID", "Cbox · Cortex" with the middle dot as separator.
+- Avoid emoji in product names. The middle dot does the same job, more elegantly.
+
+## Asset checklist (what should land in `assets/` over time)
+
+- [ ] Wordmark — full-colour, white-on-dark, monochrome variants in SVG.
+- [ ] App monograms — single-letter mark per app (I, C, A, T) sized for both 24px and 64px contexts.
+- [ ] Favicon — 32×32, 16×16 ICO + `apple-touch-icon` PNG.
+- [ ] Open Graph image template — 1200×630 PNG with the brand wordmark + a per-app variant.
+- [ ] Email-header artwork — used by the notifications module's email channel.
+
+We don't have these yet — the v0.1 of the package ships with the typography + colour + chrome contract. Logos / artwork land as they're produced.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cbox (cbox.dk)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# @cboxdk/cbox-ui
+
+Shared UI for the Cbox app family — id, cortex, atlas, track, and whatever's next.
+
+This package gives every Cbox app the same chrome (top bar, org switcher, app launcher, user menu, notifications bell) and the same page primitives (panels, headers, tabs, status pills) so cross-app navigation feels like one product. It also ships the design tokens (colours, fonts, radii) and the brand assets in one place.
+
+The package is **headless about data**: every component reads identity, organization, and notification state from a `<CboxIdProvider>` context that the consuming app populates from the future `@cboxdk/cbox-id-client` SDK. Components never fetch — they render what the host gave them.
+
+## Install
+
+```sh
+# In a Cbox-family app
+bun add @cboxdk/cbox-ui clsx tailwind-merge
+# Peer deps (you almost certainly already have these):
+bun add react react-dom tailwindcss lucide-react
+```
+
+The package is published on npm as `@cboxdk/cbox-ui` under the MIT License. The Cbox name and logos in `assets/` are trademarks and are not covered by the licence (see `TRADEMARKS.md`).
+
+## Wire it up
+
+### 1. Pull the design tokens into your CSS
+
+```css
+/* resources/css/app.css */
+@import 'tailwindcss';
+@import '@cboxdk/cbox-ui/tokens';
+```
+
+That's it — every `text-foreground`, `bg-card`, `border-border`, `text-mono`, etc. utility now resolves against the Cbox palette. Light + dark variants come bundled.
+
+### 2. Wrap the app root with `<CboxIdProvider>`
+
+In **id itself** (which IS the source of truth), populate from Inertia shared props:
+
+```tsx
+import { CboxIdProvider } from '@cboxdk/cbox-ui';
+
+export default function AppRoot({ shared, children }) {
+    return (
+        <CboxIdProvider value={shared.cboxId}>
+            {children}
+        </CboxIdProvider>
+    );
+}
+```
+
+In **cortex / atlas / track / future apps**, populate from the id-client SDK on session start:
+
+```tsx
+import { CboxIdProvider } from '@cboxdk/cbox-ui';
+import { useIdSession } from '@cboxdk/cbox-id-client';
+
+export default function AppRoot({ children }) {
+    const session = useIdSession(); // {user, organizations, currentOrg, ...}
+    return (
+        <CboxIdProvider value={session.cboxIdContext}>
+            {children}
+        </CboxIdProvider>
+    );
+}
+```
+
+The context shape is exported as `CboxIdContextValue` — see `src/context/cbox-id.tsx` for the full surface. Required keys:
+
+- `user` — `{id, name, email, avatar_url?, locale?, timezone?}`
+- `currentOrganization` — current org context (or null on user-only surfaces)
+- `organizations` — every org the user belongs to (drives the switcher)
+- `apps` — sister apps for the launcher
+- `urls` — `{idBaseUrl, accountUrl, orgSettingsUrl, switchOrgUrl, signOutUrl}`
+- `notifications?` — `{unreadCount, inboxUrl}` (optional, hides the bell when missing)
+- `onSwitchOrganization?` — callback when the user picks an org (default: form-POST to `urls.switchOrgUrl`)
+
+### 3. Drop in the chrome
+
+```tsx
+import { TopBar } from '@cboxdk/cbox-ui';
+
+<TopBar
+    brand={<MyAppLogo />}
+    centre={<MySearchBar />}
+    showOrgSwitcher
+/>
+```
+
+The default right-cluster is `<AppLauncher>` → `<NotificationsBell>` → `<UserMenu>`. Override with `rightCluster={...}` if a particular app needs a different mix.
+
+### 4. Use page primitives
+
+```tsx
+import {
+    PageShell,
+    PageHeader,
+    PageTabs,
+    DataPanel,
+    PanelBody,
+    SectionHeader,
+    StatusPill,
+    EmptyState,
+    StatTile,
+    KeyValue,
+} from '@cboxdk/cbox-ui';
+```
+
+Match id's existing patterns — see id/resources/js/pages/* for examples.
+
+## Components
+
+### Chrome (cross-app navigation)
+
+| Component | What it does |
+|---|---|
+| `TopBar` | Standard 56px-tall app bar. Slot for brand + centre + right cluster. |
+| `OrgSwitcher` | Dropdown listing the user's orgs. Calls `onSwitchOrganization` (or POSTs to `urls.switchOrgUrl`) on pick. |
+| `AppLauncher` | 9-dot grid showing sister Cbox apps the user can jump into. |
+| `UserMenu` | Avatar dropdown with "Manage account ↗" + "Team & billing ↗" (deep-links into id) + Sign out. |
+| `NotificationsBell` | Bell icon with unread badge, links to id's unified inbox. Renders nothing if context lacks `notifications`. |
+
+### Page primitives
+
+| Component | What it does |
+|---|---|
+| `PageShell` | Outer page container with vertical rhythm. |
+| `PageHeader` | Title + description + actions slot. Tab-strip-aware (no padding mismatch when followed by `PageTabs`). |
+| `PageTabs` | Tabs strip on the page baseline. Pass `currentPath` + optional `LinkComponent` (Inertia's `Link`, Next's, etc.). |
+| `DataPanel` / `PanelBody` / `SectionHeader` | The default building block for content sections. |
+| `StatusPill` | Coloured chip for status / state. Tones: success / warning / destructive / info / muted / neutral. |
+| `EmptyState` | Centred icon + heading + description for empty lists. |
+| `StatTile` | Big-number metric tile. |
+| `KeyValue` / `KeyValueList` | Definition-list style "label → value" for detail panels. |
+| `Heading` | Section heading without the panel chrome. |
+
+## Versioning
+
+This package follows semver. **Breaking changes get a major bump** — every Cbox app pinning a major version stays safe. New components, new optional props, new tokens → minor. Token tweaks that don't change the visual contract → patch.
+
+In practice during the early days (v0.x): treat every release as potentially breaking, pin exact versions, upgrade in lockstep.
+
+## Local dev against id
+
+While iterating, `bun link` the package locally so id picks up changes on rebuild:
+
+```sh
+# In cbox-ui:
+bun run build && bun link
+
+# In id:
+bun link @cboxdk/cbox-ui
+bun run dev
+```
+
+Switch back to the published version with `bun unlink @cboxdk/cbox-ui && bun install`.
+
+## Brand
+
+Brand guidelines, logo files, and the canonical asset set live in [`BRAND.md`](./BRAND.md) and `assets/`.

package/TRADEMARKS.md

@@ -0,0 +1,5 @@
+# Trademarks
+
+The code in this repository is licensed under the MIT License (see `LICENSE`).
+
+The Cbox name and the Cbox logos, wordmarks and monograms in `assets/` are trademarks of Cbox and are not licensed under the MIT License. They may be used to refer to Cbox products, but not to brand other products.

package/assets/favicon.svg

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" role="img" aria-label="Cbox">
+    <title>Cbox</title>
+    <rect x="0" y="0" width="32" height="32" rx="7" fill="oklch(0.45 0.16 258)"/>
+    <circle cx="16" cy="16" r="6" fill="oklch(0.992 0.003 247)"/>
+</svg>

package/assets/monograms/atlas.svg

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Cbox · Atlas">
+    <title>Cbox · Atlas</title>
+    <rect x="2" y="2" width="60" height="60" rx="14" fill="oklch(0.6 0.14 200)"/>
+    <text
+        x="32"
+        y="44"
+        text-anchor="middle"
+        fill="oklch(0.992 0.003 247)"
+        font-family="Plus Jakarta Sans, ui-sans-serif, system-ui, sans-serif"
+        font-weight="700"
+        font-size="40"
+        letter-spacing="-0.04em">A</text>
+</svg>

package/assets/monograms/cortex.svg

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Cbox · Cortex">
+    <title>Cbox · Cortex</title>
+    <rect x="2" y="2" width="60" height="60" rx="14" fill="oklch(0.55 0.21 295)"/>
+    <text
+        x="32"
+        y="44"
+        text-anchor="middle"
+        fill="oklch(0.992 0.003 247)"
+        font-family="Plus Jakarta Sans, ui-sans-serif, system-ui, sans-serif"
+        font-weight="700"
+        font-size="40"
+        letter-spacing="-0.04em">C</text>
+</svg>

package/assets/monograms/id.svg

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Cbox · ID">
+    <title>Cbox · ID</title>
+    <rect x="2" y="2" width="60" height="60" rx="14" fill="oklch(0.45 0.16 258)"/>
+    <text
+        x="32"
+        y="44"
+        text-anchor="middle"
+        fill="oklch(0.992 0.003 247)"
+        font-family="Plus Jakarta Sans, ui-sans-serif, system-ui, sans-serif"
+        font-weight="700"
+        font-size="32"
+        letter-spacing="-0.04em">ID</text>
+</svg>

package/assets/monograms/track.svg

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Cbox · Track">
+    <title>Cbox · Track</title>
+    <rect x="2" y="2" width="60" height="60" rx="14" fill="oklch(0.65 0.16 70)"/>
+    <text
+        x="32"
+        y="44"
+        text-anchor="middle"
+        fill="oklch(0.18 0.012 250)"
+        font-family="Plus Jakarta Sans, ui-sans-serif, system-ui, sans-serif"
+        font-weight="700"
+        font-size="40"
+        letter-spacing="-0.04em">T</text>
+</svg>

package/assets/og-template.svg

@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 630" role="img" aria-label="Cbox">
+    <title>Cbox social card template</title>
+    <!-- Background: cool near-white with a subtle blue-tinted gradient
+         in the lower right, mirroring the canvas treatment in-app. -->
+    <defs>
+        <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+            <stop offset="0%" stop-color="oklch(0.992 0.003 247)"/>
+            <stop offset="100%" stop-color="oklch(0.94 0.01 250)"/>
+        </linearGradient>
+    </defs>
+    <rect width="1200" height="630" fill="url(#bg)"/>
+
+    <!-- Mark -->
+    <g transform="translate(96 96)">
+        <rect x="0" y="0" width="120" height="120" rx="28" fill="oklch(0.45 0.16 258)"/>
+        <circle cx="60" cy="60" r="22" fill="oklch(0.992 0.003 247)"/>
+    </g>
+
+    <!-- Wordmark -->
+    <text
+        x="96"
+        y="372"
+        fill="oklch(0.18 0.012 250)"
+        font-family="Plus Jakarta Sans, ui-sans-serif, system-ui, sans-serif"
+        font-weight="700"
+        font-size="120"
+        letter-spacing="-0.04em">Cbox</text>
+
+    <!-- Tagline slot — replace per-app/per-page when generating actual cards. -->
+    <text
+        x="96"
+        y="446"
+        fill="oklch(0.5 0.012 250)"
+        font-family="Plus Jakarta Sans, ui-sans-serif, system-ui, sans-serif"
+        font-weight="500"
+        font-size="36"
+        letter-spacing="-0.01em">Identity, billing, and entitlements for the Cbox family.</text>
+
+    <!-- Footer rule -->
+    <rect x="96" y="538" width="64" height="3" fill="oklch(0.45 0.16 258)"/>
+    <text
+        x="96"
+        y="572"
+        fill="oklch(0.5 0.012 250)"
+        font-family="JetBrains Mono, ui-monospace, monospace"
+        font-weight="500"
+        font-size="20"
+        letter-spacing="0.04em">CBOX.DK</text>
+</svg>

package/assets/wordmark-mono.svg

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 220 56" role="img" aria-label="Cbox">
+    <title>Cbox (monochrome)</title>
+    <rect x="4" y="12" width="32" height="32" rx="8" fill="currentColor"/>
+    <circle cx="20" cy="28" r="6" fill="oklch(0.992 0.003 247)"/>
+    <text
+        x="50"
+        y="37"
+        fill="currentColor"
+        font-family="Plus Jakarta Sans, ui-sans-serif, system-ui, sans-serif"
+        font-weight="600"
+        font-size="28"
+        letter-spacing="-0.02em">Cbox</text>
+</svg>

package/assets/wordmark.svg

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 220 56" role="img" aria-label="Cbox">
+    <title>Cbox</title>
+    <!-- Mark: rounded square with a single deep-blue dot. The geometric
+         opposite of the wordmark's restraint — small, decisive. -->
+    <rect x="4" y="12" width="32" height="32" rx="8" fill="oklch(0.45 0.16 258)"/>
+    <circle cx="20" cy="28" r="6" fill="oklch(0.992 0.003 247)"/>
+    <!-- Wordmark: Plus Jakarta Sans, semibold, slightly tightened tracking.
+         Path-based so we don't depend on the font being embedded. -->
+    <text
+        x="50"
+        y="37"
+        fill="oklch(0.18 0.012 250)"
+        font-family="Plus Jakarta Sans, ui-sans-serif, system-ui, sans-serif"
+        font-weight="600"
+        font-size="28"
+        letter-spacing="-0.02em">Cbox</text>
+</svg>