@4242labs/design-system

The 42labs Design System as an installable package: the tokens, the 29 registry primitives, and the portable compliance check that every consuming project runs in CI.

The canonical reference is https://ds.42labs.io. This package is generated from that repository's own sources at build time — it is not a second copy, and it cannot drift from what the registry serves.

Install

npm install @4242labs/[email protected]

Pin the exact version. The compliance check fails a range: a range lets an install move off the pin with no change in the consuming project, which is the one thing the pin is for.

Tokens

@import "@4242labs/design-system/tokens.css";

tokens.css is byte-identical to the published tokens.v<version>.css. Projects using Tailwind also import the bridge:

@import "@4242labs/design-system/tailwind.css";

Both are declared side effects, so a bundler will not tree-shake them away.

Components

Every export is explicit; there is no wildcard and no root export.

import { Button } from "@4242labs/design-system/components/button";
import { cn } from "@4242labs/design-system/utils";
import { useIsMobile } from "@4242labs/design-system/hooks/use-mobile";

React and Tailwind are optional peers. A project consuming tokens as plain CSS — no React, no Tailwind — installs cleanly and pulls in neither.

Compliance check

npx --package=@4242labs/[email protected] -- \
  42labs-ds-check --scan "src" --expect "2.4.5"

The checker version and the token pin are separate values. A defective checker is rolled back by moving the npx specifier back one patch; --expect does not move, so the pin does not move and no retrofit is triggered.

It asserts:

| Gate | Fails on | |:--|:--| | package | manifest pin, lockfile entry and installed version disagreeing, a range instead of an exact version, a lockfile resolved anywhere but the public registry, or missing sha512 integrity | | vendored-copy | a second copy of the package's tokens.css or tailwind.css anywhere in the tree, or no stylesheet importing them | | 1 | a raw colour — hex, rgb(), hsl(), or a Tailwind palette class | | 2 | an arbitrary design value that is not a token reference | | 3 | a bespoke primitive where an adopted one exists |

Scanned extensions: .ts, .tsx, .js, .jsx, .mjs, .cjs, .css, .html.

The package gate only runs when the consuming project declares this package.

Gates 1 to 3 are own-code gates, so adopted registry primitives are exempt. --ui-dir names where they live and defaults to src/components/ui; pass --ui-dir "" to scan everything.

Rehearsing an unpublished build

42labs-ds-check --scan src --expect 2.4.5 \
  --tarball ./4242labs-design-system-2.4.5.tgz --sha256 <hex>

Rehearsal mode verifies the tarball's hash, name and version against a file: install. It claims nothing about registry integrity, because there is not yet anything published to claim it of.

The one escape

// drift-allow(2026-12-31): upstream widget ships this hex and we do not control it
const brand = "#ff6600";

It expires, and the reason must be at least twelve characters. An expired marker fails. A malformed one fails. Every live marker is reported in the output and in the fleet's nightly report, so an exception is visible rather than forgotten.

Programmatic

import { checkConsumer } from "@4242labs/design-system/check";

const { ok, findings, driftAllows } = await checkConsumer({
  cwd: process.cwd(),
  scan: ["src"],
  expectedVersion: "2.4.5",
});

checkConsumer makes no network call, writes nothing, and never calls process.exit.

Versioning

One SemVer stream, shared with the design system itself. CHANGELOG.md in the repository is the source of truth. Removing or renaming an export requires a dated operator amendment.

Licence

MIT. See THIRD_PARTY_NOTICES for the upstream primitives this system re-themes.