Kingsbridge Design Library

Publishable React component library and design tokens for Kingsbridge, with Storybook as the primary docs surface.

Figma: Kingsbridge Design Library — Foundations

Install

npm install kingsbridge-design-library

Peer dependencies: react and react-dom ^19, and @base-ui/react ^1 (required once compound components that wrap Base UI ship; install it now to match the library’s peer range).

Usage

import {
  Button,
  TextLink,
  Tag,
  Logo,
  Icon,
  ArrowRightIcon,
  DropDownSmall,
  cn,
} from 'kingsbridge-design-library'
import 'kingsbridge-design-library/styles.css'

Tokens only (no component CSS Modules):

import 'kingsbridge-design-library/tokens.css'

Component conventions

| Tier | When | Pattern | Examples | |------|------|---------|----------| | Leaf | Single DOM node, visual variants | Flat props + cva + CSS Modules | Button, Tag, TextLink, Logo, Menu (toggle), LanguageSelect | | Compound | Shared state / composed parts | Namespace exports — Base UI (@base-ui/react) or visual compounds | DropDownSmall; FormField; Icon; Illustration |

Foundations sub-tiers (Storybook sidebar): Primitives (interactive, exported), Layout (structural helpers, internal — includes Content for section inset rails), Display (named UI patterns, exported), Specimens (docs-only). Layout, Specimens, and TagList stay in src/components/ but are not on the package root — import them inside the library or copy patterns from Storybook.

Icon / Illustration / HeroIcon are flat one-element APIs: <Icon.ArrowRight size="md" />, <Icon.Category name="bones" />, <HeroIcon.Bell size="xl" />, <Illustration.Service name="bones" size="lg" />. Heroicons are a separate component (peer @heroicons/react) — not nested under Icon. UI glyphs match Figma Archive/Button Icons (2296:27060). Background leaf stays LeafMotif (Layout / Storybook-only).

• No Tailwind. Styling is CSS Modules + --kb-* custom properties only. cn is a thin clsx helper for class merges — not tailwind-merge.
• Leaf variants use cva mapped to CSS Module classes; always pass consumer className through last.
• Compound components use Base UI’s render prop for polymorphism (not Radix asChild) and [data-*] selectors for interactive state.
• When library conventions change, docs (README, AGENTS.md, Storybook MDX, Cursor rules) update in the same change.

Style schemes

Default is Style Scheme 1 on :root. Nest schemes on any subtree:

<html class="style-scheme-1">
  …
  <section class="style-scheme-3">Dark band</section>
</html>

Fonts

| Role | Family | Notes | |------|--------|--------| | Headings (H1 XL–H3) | Sentient Medium | Self-hosted woff2 under src/assets/fonts/sentient/ (Fontshare FFL). Fallbacks: "Iowan Old Style", "Palatino Linotype", Palatino, "Times New Roman", serif | | UI / body | Figtree | Loaded via Google Fonts @import in src/styles/fonts/figtree.css |

Importing kingsbridge-design-library/styles.css pulls both. For tokens-only installs, also import fonts:

import 'kingsbridge-design-library/fonts.css'
import 'kingsbridge-design-library/tokens.css'

Typography sizes follow the Foundations type ramp (responsive px per style). Spacing uses the shared modular scale round(16 × ratio^n).

Scripts

| Script | Purpose | |--------|---------| | npm run storybook / npm run dev | Storybook 10 on :6006 (a11y + Design/Figma panel) | | npm run build | Library build → dist/ (ES + types + CSS) | | npm run build-storybook | Static Storybook → storybook-static/ | | npm run lint | Oxlint |

Deploy Storybook (Vercel)

vercel.json builds Storybook static output. Connect the repo and deploy; no extra project settings required beyond the defaults in that file.

Package layout

src/
  styles/tokens/   # brand, schemes, scale, typography, semantic
  components/      # Foundations (Primitives + Display + Layout helpers)
  blocks/          # Mid-level composed UI (Cards, CTAs, Filters, Forms, …)
  sections/        # Page-level compositions (Hero, Header, Footer, …)
  pages/           # Page template compositions (Storybook-only)
  lib/             # cn (clsx)
  index.ts         # public API
.storybook/        # docs + a11y

Blocks assemble Foundations into Figma Blocks-page patterns. Story titles use Blocks/<section>/…. Figma breakpoint variants are implemented with CSS media queries and the modular scale — not size="mobile" props.

Sections assemble Blocks + Foundations into Figma Sections-page layouts. Story titles use Sections/<category>/… (Promote, Act, Decorative, Inform, Navigate, Waiting Times). All six categories are implemented and exported from the package root (LocationsSection / OptionsSection / WaitingTimeTableSection / AccordionSection / CallOutSection / CostsSection aliases avoid name collisions with Foundations/Blocks).

Pages stack Sections into recurring site templates (homepage, index/finder, clinical content, profile, practical information, forms, editorial). Story titles use Pages/<family>/…. Not exported from the package root — use as reference orderings when building WordPress or app pages.