@crometrics/lp-design-system

React 18/19 component library for landing pages. Ships unbundled ESM (one module per component) and a standalone stylesheet; consumers theme it exclusively through --lp-* CSS variables and need no Tailwind setup of their own.

Install

The package is published publicly to npm:

pnpm add @crometrics/lp-design-system

Releases through 0.5.0 also went to GitHub Packages; later ones are on npm only. The other @crometrics packages are still published to GitHub Packages. If your .npmrc (project or ~/.npmrc) maps the scope there — @crometrics:registry=https://npm.pkg.github.com/ — that mapping applies to every @crometrics package, so the command above resolves against GitHub Packages and never sees npm releases. Either remove the mapping if you need no other @crometrics packages, or pin this one package to npm with pnpm's npmjs: registry prefix (pnpm 11.1+):

pnpm add "@crometrics/lp-design-system@npmjs:^0.5.0"

which saves "@crometrics/lp-design-system": "npmjs:^0.5.0" to package.json, so updates keep coming from npm while other @crometrics packages still resolve from GitHub Packages. npm and Yarn have no per-package registry override.

react and react-dom ^18.0.0 || ^19.0.0 are peer dependencies and must be installed by the consumer. Every story test runs on both React 18.3.1 (what HubSpot CMS React pins) and React 19.

Usage

Import the stylesheet once at the app root, then use components anywhere:

// app entry (e.g. src/main.tsx, or app/layout.tsx in Next.js)
import '@crometrics/lp-design-system/styles.css';

Import each component from its own entry point — the kebab-case component name:

import { Button } from '@crometrics/lp-design-system/button';
import { PromoBanner } from '@crometrics/lp-design-system/promo-banner';

Per-component entry points load only that component's modules in every tool: production bundles, dev servers, and test runners alike. Importing from the package root (import { Button } from '@crometrics/lp-design-system') also works and tree-shakes in production builds, but dev servers and test runners load every component through it.

import { Button } from '@crometrics/lp-design-system/button';

export default function Page() {
  return (
    <>
      <Button>Primary</Button>
      <Button variant="secondary" size="lg">
        Secondary
      </Button>
      <Button variant="tertiary" icon={<CameraIcon />}>
        With icon
      </Button>
      <Button
        variant="transparent"
        icon={<img alt="" src={logo} />}
        iconPosition="trailing"
      >
        On a hero image
      </Button>
      <Button aria-label="Add photo" icon={<CameraIcon />} round />
    </>
  );
}

Server rendering and hydration

Every component server-renders (verified with renderToString on React 18 and 19). Only two need client hydration — in HubSpot CMS React, render them as islands:

Everything else — including Header, TrustSignalsMetrics, ThirtyNinety, PromoBanner, Accordion (Base UI hydrates its own primitive) and FooterMega — ships no component JavaScript. With formSlot, DonationHero needs no hydration of its own beyond whatever the slotted vendor embed brings.

Components are also RSC-safe: only Tout and DonationForm are marked 'use client', so everything else renders on the server in Next.js App Router and ships no component JavaScript to the browser. Both can be rendered directly from a server component — no wrapper file needed. Frameworks without RSC (Vite SPAs, Astro, plain React) ignore the directive.

Props passed from a server component must be serializable: event handlers such as Input's onChange or EmailSignupForm's onSubmit can only be supplied from a client component.

Theming

--lp-* custom properties are the entire public styling API. Defaults are declared on :root in styles.css; override any of them in your own CSS, loaded after the library stylesheet:

:root {
  --lp-color-primary: #16a34a;
}

Defaults mirror the Figma "Landing Page Design System" library.

Breakpoints

Layouts follow the design's three page frames: mobile < 1024px, desktop 1024–1727px, wide ≥ 1728px. Responsive token defaults switch at those widths, and themes override responsive tokens inside the same media queries:

:root {
  --lp-text-h1-cms-size: 2.5rem;
} /* mobile + desktop */
@media (min-width: 1728px) {
  :root {
    --lp-text-h1-cms-size: 4rem;
  } /* wide */
}

Before 0.5.0 the wide tier started at 1280px.

The stylesheet never resets your page. It does reset inside its own components: every component root carries a data-lp attribute, and a zero-specificity reset (Tailwind's preflight, scoped to [data-lp] subtrees) clears browser defaults there, such as heading and paragraph margins, link color and underline, and native button borders. The reset sits in the lp-base cascade layer and the utility classes in lp. Any unlayered CSS on your page outranks both, so a global rule like h2 { margin-bottom: 1rem } in your theme still reaches our headings. Scope such rules away from [data-lp] if they interfere. Class names other than these variables are implementation detail and may change in any release.

Components

Every section's full CMS-facing shape (props, toggles, repeaters, variants, slots) is in contracts/<Name>.json. Additions in 0.5.0, all optional with defaults that keep the previous rendering:

Additions in 0.6.0, also optional with defaults that keep the previous rendering:

Additions in 0.7.0, also optional with defaults that keep the previous rendering:

CtaLink ({ href, label, newTab?, id?, dataAttributes? }) is the CTA shape for Header, TrustSignalsMetrics, ThirtyNinety and PromoBanner. id and dataAttributes (keys must start with data-; others are dropped) are rendered on the CTA element, so your own scripts can target it, e.g. for analytics or to open a third-party donation form such as FundraiseUp:

<Header
  logo={logo}
  ctas={[
    {
      link: {
        label: 'Get started',
        href: '#signup',
        dataAttributes: { 'data-track': 'header-primary' },
      },
      hideOnMobile: true,
    },
    { link: { label: 'Contact us', href: '#contact', id: 'header-contact' } },
  ]}
/>;

FooterMega signup form

FooterMega renders whatever form you pass as signupSlot: a CMS form module, an email-provider embed, or your own markup. It can't know that markup, so signupFormSelectors tells it which of your elements gets each part of the signup design. Every key is optional and takes any CSS selector list, matched inside that footer's slot only. Elements no key matches inherit the slot's font, size and color.

For example, for a form module whose markup uses .hs-* classes, as HubSpot's does:

<FooterMega
  {...footerProps}
  signupFormSelectors={{
    error: '.hs-error-msgs',
    field: '.hs-input:not([type=checkbox], [type=radio])',
    fieldInvalid: '.hs-input.error',
    fieldRow: 'fieldset',
    form: '.hs-form',
    hiddenLabel:
      '.hs-form-field:not(.hs-fieldtype-checkbox, .hs-fieldtype-booleancheckbox, .hs-fieldtype-radio) > label',
    hint: '.hs-richtext',
    inlineField: 'fieldset:last-of-type',
    inlineSubmit: '.hs-submit',
    reset: '.input, .actions',
    submit: '.hs-button',
  }}
  signupSlot={<YourFormModule />}
/>

The footer renders these rules in a <style> inside the slot, in the lp layer, so your own CSS still overrides them; the few layout declarations that embeds' own stylesheets usually fight (widths, floats, wrapper margins, hidden labels) are !important. Colors follow style and the --lp-* variables. A selector containing {, }, ;, < or a comment throws. For an element that needs a look none of these keys gives, style it in your own CSS under [data-lp-part="signup-slot"] with the --lp-* variables.

Typed contracts

contracts/<Name>.json (described by contracts/component.schema.json) widens every literal when imported as JSON. @crometrics/lp-design-system/contracts exports the same data with its literal types, as <Name>Contract, plus the types to work with it:

import {
  type ContractProp,
  type ContractValues,
  HeaderContract,
} from '@crometrics/lp-design-system/contracts';

// Props, variants and repeater items share one union, discriminated on `type`.
const field = (prop: ContractProp) => {
  switch (prop.type) {
    case 'enum':
      return prop.options; // readonly [string, ...string[]]
    case 'link':
      return prop.fields; // subset of 'label' | 'href' | 'newTab' | 'id' | 'dataAttributes'
    // …
  }
};

// The props a contract describes: { logo: { src; alt }; logoSize?: 'md' | 'lg'; … }
type HeaderValues = ContractValues<typeof HeaderContract>;

ContractValues maps text to string, boolean, number, enum to its options, image to { src, alt } and link to Pick<CtaLink, …fields>. A richtext prop follows its render mode: html props are injected with dangerouslySetInnerHTML, so they take the CMS's HTML string; node props are rendered as a React child, so they take a ReactNode. Turn the HTML into elements for those (a raw HTML string would show escaped). A repeater becomes an array: a required non-empty tuple [T, ...T[]] when min ≥ 1, else optional. Dotted keys (form.submitLabel) become nested objects. required controls whether a key is optional, and variants are always optional. hidden props and slots are left out (a slot is a ReactNode prop, like formSlot or signupSlot, that you render yourself), and so are countFrom variants such as BannerGrid's quantity: they only size their repeater, and the component reads the array's length. Also exported: Contract, ContractVariant, ContractRepeater, ContractSlot, ContractPropValue<P>, ContractRichtextRender, and one interface per prop type (TextProp, RichtextProp<Render>, EnumProp, LinkProp, …).

mapContract

@crometrics/lp-design-system/contracts/map walks a contract for you. You supply one typed reader per leaf type, and it returns ContractValues<C>, with no assertion on your side:

import { ToutContract } from '@crometrics/lp-design-system/contracts';
import {
  type ContractReaders,
  mapContract,
} from '@crometrics/lp-design-system/contracts/map';

const text = (value: unknown) =>
  typeof value === 'string' ? value : undefined;

const read: ContractReaders = {
  boolean: (value) => (typeof value === 'boolean' ? value : undefined),
  enum: text, // mapContract drops values that aren't one of the options
  image: (value) => toImage(value),
  link: (value) => toCtaLink(value),
  number: (value) => (typeof value === 'number' ? value : undefined),
  richtext: {
    html: text, // must return a string
    node: (value) =>
      typeof value === 'string' ? htmlToReact(value) : undefined,
  },
  text: (value, prop) => text(value) ?? prop.default,
};

const props = mapContract(ToutContract, fieldValues, read); // ToutProps-compatible

Each reader gets the raw value, the prop's contract entry and its path (sectionHeading, cards[1].body, variants.cards). fieldValues mirrors the contract: props and repeaters sit at their dotted keys ({ form: { submitLabel } }), repeaters are arrays of item objects, and variants go under variants, the same way countFrom names them ({ cards: […], variants: { cards: '3' } }). Hidden and slot props are skipped. A countFrom repeater is trimmed to its variant's value (or its default). A reader that returns undefined leaves the prop out, so the component default applies. For a required prop, or a min ≥ 1 repeater that ends up empty, mapContract throws instead, because the props type promises a value. Fall back to prop.default in the reader to avoid that.

A few contracts don't describe their component's props exactly, so the CMS adapter has to map these fields itself. contracts/props.test-d.ts pins each one, and any other difference between a contract and its component fails the type tests:

Development

Run from this package directory:

pnpm storybook   # dev at http://localhost:6006
pnpm test        # runs the stories headless via addon-vitest
pnpm build       # dist/*.js per component (tsdown) + dist/styles.css (@tailwindcss/cli)

Stories are the tests: every component behavior is asserted in a *.stories.tsx play function rather than a separate spec file.