@openkeyai/ui

v2.0.6

Published

8 days ago

Design system + mandatory HubHeader for OpenKey AI tools.

0High
0Medium
0Low

slgoodwin

`@openkeyai/ui`

The shared design system + mandatory <HubHeader /> for every OpenKey AI tool.

pnpm add @openkeyai/ui
# or
npm i @openkeyai/ui

Mounting `<HubHeader />`

Every tool must mount the header in its root layout. The OpenKey AI CI scanner (lands in Phase 9) enforces this — a tool repo's build will fail if the import + mount aren't both present.

Next.js (App Router)

// app/layout.tsx
import "@openkeyai/ui/css";
import { HubHeader } from "@openkeyai/ui";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  // `user` comes from your tool's session helper (Phase 8's SDK ships one).
  return (
    <html lang="en">
      <body style={{ paddingTop: "var(--okai-header-h)" }}>
        <HubHeader
          toolName="YouTube Thumbnails"
          user={{
            displayName: "Scott G.",
            avatarUrl: null,
            email: "[email protected]",
          }}
        />
        <main>{children}</main>
      </body>
    </html>
  );
}

The header is fixed-position at z-index: var(--okai-z-header) and var(--okai-header-h) (56px) tall. Leave that much top padding on your root.

Signed-out state

Pass user={null} (or omit) and the chip is replaced by a Sign in CTA that links back to https://openkeyai.com/login. Don't try to hide the chip altogether — it's part of the consistent user experience contract.

Tokens + Tailwind

Two consumption paths besides the CSS sheet:

Tailwind preset

// tailwind.config.ts
import type { Config } from "tailwindcss";
import { hubTailwindPreset } from "@openkeyai/ui/tailwind";

export default {
  presets: [hubTailwindPreset],
  content: [
    "./app/**/*.{ts,tsx}",
    "./node_modules/@openkeyai/ui/dist/**/*.{js,cjs}",
  ],
} satisfies Config;

Now bg-okai-bg, text-okai-foreground, rounded-okai-xl, pt-okai-header etc. are available alongside Tailwind's defaults.

Direct token access

import { tokens } from "@openkeyai/ui/tokens";

const indigo = tokens.color.accent; // "#7c6cf5"

Use this for places utility classes can't reach — SVG gradients, canvas paints, programmatic colour pickups.

What you CANNOT do with `<HubHeader />`

Hide the OpenKey AI brand mark
Hide the user chip / sign-in CTA
Replace the brand wordmark
Change the header height or position
Theme it to match your tool's brand only

The header is the shared trust surface — users need to recognise it across every tool. The rightSlot prop is the legitimate extension point for tool-specific controls (settings, help, share, …); they render to the left of the user chip.

If you have a legitimate need that the current API doesn't cover, open an issue rather than monkey-patching the package. Major version bumps require 60 days notice to tool authors.

API

`HubHeader`

type HubHeaderProps = {
  toolName: string;
  user?: {
    displayName: string;
    avatarUrl?: string | null;
    email?: string;
  } | null;
  hubUrl?: string;     // default: "https://openkeyai.com"
  rightSlot?: React.ReactNode;
  className?: string;
  style?: React.CSSProperties;
};

Versioning

This package follows semver. Breaking changes to <HubHeader /> are major-version bumps and require the 60-day notice flow described above. Token additions are minor; pure-CSS tweaks are patch.

UI_VERSION is re-exported from the entry so tools can log which build they shipped against:

import { UI_VERSION } from "@openkeyai/ui";
console.log("openkeyai/ui", UI_VERSION); // → "0.1.0"

Development

pnpm install
pnpm dev        # tsup --watch
pnpm build      # tsup
pnpm typecheck
pnpm test

License

MIT — see LICENSE.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme