Wisent Components

@wisent-ai/components and the WisentDesignSystem Swift package are the runtime source of truth for shared Wisent design tokens and reusable interface components. Wisent applications consume them instead of copying brand colors, spacing, radii, typography, panels, badges, buttons, page headers, metrics, loading states, or accessibility behavior into each repository.

The repository also retains the versioned Figma source snapshots under figma/. Figma records design intent; tokens.json and the exported components are the implementation contract applications execute.

The documentation system — the shared DocumentationLayout convention, every product's docs structure, and how the system evolved — is recorded in docs/DOCUMENTATION.md.

Use it

Web consumers require Node.js 20 or newer and React 18 or 19. Native consumers require Swift 6 and macOS 14 or iOS 17. The repository is private, so both package managers use the consuming environment's existing GitHub credentials.

npm install github:wisent-ai/wisent-components

Import the stylesheet once in the application's global stylesheet:

@import "@wisent-ai/components/styles.css";

Then use the shared interface primitives without coupling UI to an application framework:

import {
  GitHubLoginButton,
  GoogleLoginButton,
  WisentButton,
  WisentPageHeader,
  WisentPanel,
} from "@wisent-ai/components";

export function AccountPage({ loadingProvider, signIn }) {
  return (
    <>
      <WisentPageHeader
        eyebrow="Account"
        title="Connect to Wisent"
        description="One visual contract across Wisent applications."
      />
      <WisentPanel>
        <GoogleLoginButton
          loading={loadingProvider === "google"}
          onClick={() => signIn("google")}
        />
        <GitHubLoginButton
          loading={loadingProvider === "github"}
          onClick={() => signIn("github")}
        />
        <WisentButton>Continue</WisentButton>
      </WisentPanel>
    </>
  );
}

Native applications add the repository as a Swift package and import the product:

import SwiftUI
import WisentDesignSystem

struct Overview: View {
    var body: some View {
        WisentPanel {
            WisentPageHeader(
                eyebrow: "Operations",
                title: "Brama",
                detail: "Private model routing on this Mac.",
                symbol: "point.3.connected.trianglepath.dotted"
            )
        }
        .background { WisentCanvasBackground() }
    }
}

A successful integration renders branded, keyboard-focusable buttons and leaves provider authentication, redirects, and session state with the consuming application. Production consumers pin the dependency to an exact commit so every deployed interface remains attributable and rollback is a dependency-revision change.

Contract

The package currently owns:

• the full brand, grayscale, semantic color, typography, spacing, radius, shadow, and motion token set reconciled from Wisent App, Wisent Landing, and Wisent iOS;
• reusable React buttons, panels, badges, page headers, metric cards, OAuth actions, provider icons, generic icon wrappers, and layout primitives;
• the Figma application families: brand marks, top bars, sidebar navigation, side menus, app shells, chats, project cards and showcases, capability-model presentations, empty states, modals, and status panels;
• reusable SwiftUI canvas, panel, page and section headers, metric cards, badges, empty states, typography, colors, and button styles;
• the complete landing-page runtime: header, hero, recognition, mechanism, proof, objection, decision, footer, and page assembly;
• landing-components.json, which describes every landing component, its export, zone, and content contract for the landing pipeline;
• figma-components.json, which maps recurring structures in the three shared Figma files to their generic runtime implementation and states which data remains consumer-owned;
• bundled Hubot Sans, Hubot Sans Expanded, and IBM Plex Mono assets used by the shared components;
• loading, disabled, focus-visible, reduced-motion, Dynamic Type, dark appearance, and accessible-name behavior.

It deliberately does not own authentication, routing, translations, product-specific copy, project names, model capabilities, glyph artwork, or product state. Those values enter generic components through props. A component enters this package only when at least two applications can consume the same API.

tokens.json records the Figma file key and version from which the initial runtime values were reconciled. Change tokens there, run npm run build, and commit the generated dist/ output with the source change. Applications must not override component internals; supported variation is exposed through component props and CSS custom properties.

Figma component families

Version 0.6.0 covers every literal reusable component in Wisent App, Wisent Web, and Wisent Web App: 340 components and 56 component sets. There are two deliberate runtime paths:

• WisentFigmaComponent renders the checked-in literal Figma tree: source bounds, nesting, copy, paints, typography, effects, and the 16 image fills actually referenced by the reusable components;
• WisentFigmaFamilyComponent renders the same registry entry through a reusable semantic contract, for products replacing the design's literal copy and data.

This keeps fidelity and reuse separate. The old registry silently mapped every literal component to one of 18 approximate families; it covered ids, not the design. The literal renderer is now the default.

Figma family	Runtime contract
Wisent_logo, named glyph components	WisentBrandMark, WisentIcon
Button, CompactButton, ButtonDefault, ButtonHero, BadgeButton, BadgeButtonSmall	WisentAction variants and sizes
Badge App	WisentAppBadge
TopBar	WisentTopBar
all Sidebar navigation variants	WisentSidebarNavigation
SideMenuContainer, App	WisentSideMenu, WisentAppShell
Chat	WisentChat
Gercin card, project collections	WisentProjectCard, WisentProjectShowcase
Capabilities-Based Models/*, including Representation Engineering and Hallucination Detection	WisentCapabilityModel
repeated auto-layout stacks, rows, grids, dividers, and surfaces	WisentStack, WisentCluster, WisentGrid, WisentDivider, WisentSurface
empty, modal, and status states	WisentEmptyState, WisentModal, WisentStatusPanel

figma-components.json describes the public semantic families. figma-component-inventory.json is the exact Figma inventory, while figma-component-registry.json records every source-local node id, family, and variant defaults. The generated figmaSnapshots payload holds the literal node trees. The package build refuses a missing component or component set, duplicate registry key, unresolved set membership, unknown implementation, runtime export without a type declaration, type declaration without a runtime export, or unknown Figma source.

The capability presentation is intentionally project-neutral:

<WisentCapabilityModel
  title={project.title}
  description={project.summary}
  capabilities={project.capabilities}
  activeCapability={selectedCapability}
  stages={project.pipeline}
  tokens={project.tokens}
  metrics={project.metrics}
  controls={controls}
/>

Representation Engineering and Hallucination Detection therefore use the same layout contract with different data. A new capability project does not require a new component.

Render one literal component by stable source + node id:

<WisentFigmaComponent
  source="Wisent Web"
  id="670:863"
  text={{ "Button label": "Start" }}
  overrides={{
    "670:865": { props: { onClick: start }, style: { pointerEvents: "auto" } },
  }}
/>

Overrides are keyed by Figma node id or node name. They can replace text, children, style, DOM props, or one complete node. assetBaseUrl relocates the bundled image fills; imageResolver gives an application complete control over asset URLs. The stored Figma REST payload does not contain vector path geometry, so a consumer that needs literal icon outlines supplies vectorRenderer or replaces those named nodes. The package never invents a substitute glyph.

Use the project-neutral family instead when the layout is the contract:

<WisentFigmaFamilyComponent
  source="Wisent Web"
  id="670:863"
  href="/start"
>
  Start
</WisentFigmaFamilyComponent>

resolveFigmaComponent returns the registry mapping, resolveFigmaComponentSet returns its variants, and resolveFigmaSnapshot returns the literal node tree. Figma node ids are file-local, so every resolver uses <source>:<id> keys and rejects ambiguous id-only lookups.

Interfaces and compatibility

Interface	Contract
@wisent-ai/components	React components and provider icons
@wisent-ai/components/styles.css	generated tokens, bundled fonts, and component styles
@wisent-ai/components/tokens	JavaScript token object
@wisent-ai/components/tokens.json	framework-neutral token source
@wisent-ai/components/landing-components	React landing components used by generated pages
@wisent-ai/components/landing-components.json	machine-readable landing component descriptions and content contracts
@wisent-ai/components/figma-components	Figma-derived reusable semantic families
@wisent-ai/components/figma-components.json	machine-readable Figma-family-to-runtime mapping
@wisent-ai/components/figma-registry	inventory resolver plus literal and semantic renderers
@wisent-ai/components/figma-snapshot	literal snapshot resolver, renderer, asset map, and node trees
@wisent-ai/components/figma-component-inventory.json	exact 340-component and 56-set source inventory
@wisent-ai/components/figma-component-registry.json	exact per-node runtime mapping and variant defaults
WisentDesignSystem	SwiftUI colors, typography, surfaces, badges, metrics, headers, empty states, and buttons

The package uses semantic HTML and has no dependency on Next.js, Tailwind, Radix, Supabase, or another authentication provider. React is a peer dependency so applications retain one React runtime.

Versioning, rollback, and support

package.json is the semantic version source. There is no npm or immutable release publication yet; the supported distribution is a private Git dependency pinned to a full commit SHA. Upgrade by changing that SHA, and roll back by restoring the prior SHA and lockfile entry.

Source and defects live in the private wisent-ai/wisent-components repository. Security reports use a private GitHub Security Advisory. The package is internal and unlicensed for external distribution.