@keystone-sites/marketing-design-system

The design system behind Keystone's marketing surfaces (keystone.com and the Grader). Source-shipped TypeScript and CSS for Next.js 16 / React 19; the consumer transpiles it (transpilePackages).

What it owns

• tokens/ — fonts, primitive and semantic color, type, motion. Light is the default; themes/inverted.css is the dark theme.
• base.css, grid/ — reset, the container-query tick grid (--t), named gates (@container (--rs|--rt|--rd1|--rd2)) and the PostCSS plugin that resolves them (grid/gates.cjs).
• primitives/ — every reusable component: buttons, fields, cards, slider, FAQ question, plan/persona/case-study cards, TOC, ramps, picture, slug…
• sections/ — shared chrome (nav, footer, FAQ, gallery overlay, site chat) and the landing kit (sections/landing.tsx + hero/benefits/quote/closer).
• icons.tsx, media.ts, site-links.ts, site.ts, lib/ — brand icons, the media index, Keystone's canonical links, small runtime helpers.
• assets/media/ — the licensed fonts and brand marks. Copy them into the consumer's public/media/ (the CSS references /media/fonts/* and /media/brand/* by absolute URL).

Using it

// app/layout.tsx
import "./site.css"; // your cascade, see below
import "@keystone-sites/marketing-design-system/widgets.css";

/* site.css — one file assembles the cascade */
@import "@keystone-sites/marketing-design-system/index.css";
/* optional: the inverted (dark) theme, into the skin layer; then name it
   on <html data-theme="inverted"> for the whole product, or on one host */
@import "@keystone-sites/marketing-design-system/themes/inverted.css" layer(skin);
/* your own sections and pages */
@import "./sections/hero.css" layer(sections);
@import "./pages/home.css" layer(pages);

// postcss.config.mjs
import { fileURLToPath } from "node:url";
const gates = fileURLToPath(
  new URL("./node_modules/@keystone-sites/marketing-design-system/grid/gates.cjs", import.meta.url),
);
export default { plugins: { [gates]: {}, "@tailwindcss/postcss": {} } };

Add @keystone-sites/marketing-design-system to transpilePackages in next.config.ts, and copy css-vars.d.ts into your project (or include it from node_modules) so style={{ "--n": 3 }} type-checks.

Components are imported by subpath, extensionless:

import { GridField } from "@keystone-sites/marketing-design-system/grid/field";
import { NavChrome } from "@keystone-sites/marketing-design-system/sections/nav";
import { ButtonFill } from "@keystone-sites/marketing-design-system/primitives/buttons";

Developing

npm install         # the package's tooling and the catalog workspace
npm run check       # typecheck, lint, format, unit tests, and the catalog's checks
npm run catalog     # the catalog on http://localhost:3140 — the system rendered from source
npm run type-css    # tokens/type-styles.json → tokens/type.css
npm run exports     # regenerate the exports map after adding or moving a file

catalog/ is a Next app in this repo (an npm workspace, not published) that mounts every token, type style, primitive, and shipped section from the package by symlink, so an edit shows on the next request. Its visual gate: npm run build -w catalog && npm run start -w catalog, then npm run test:visual -w catalog (baselines in catalog/tests/__screenshots__, gitignored; -- --update-snapshots refreshes them from a reference build).

Link a consumer with "@keystone-sites/marketing-design-system": "file:../keystone-marketing-design-system" and install-links=true in its .npmrc; npm install there copies the current source in. The laws of the system (type, motion, gates, layers) are in the headers of primitives/text.css, tokens/motion.css, grid/engine.css, and index.css.