@cronos-labs/ui

Shared Header, Footer, SEO, locale and theme primitives for Cronos web properties. Consumed by cronos-landingpage-webui, cronos-bridge-webui and cronos-launch-webui so the three surfaces stay visually and behaviourally identical without copying code between them.

The package is published publicly on npm; this repository is private.

Install

npm install @cronos-labs/ui

Peer dependencies

Required — the package will not work without them:

| Package | Range | | ------------------- | --------- | | react | ^19.1.0 | | react-dom | ^19.1.0 | | styled-components | ^6.1.15 | | react-router-dom | ^7.1.5 |

Optional — only needed if you consume the shared ESLint config (@cronos-labs/ui/eslint-config):

@eslint/js, eslint, eslint-config-prettier, eslint-plugin-react-hooks, eslint-plugin-react-refresh, globals, typescript-eslint.

Entry points

The package ships compiled ESM plus type declarations. Four subpath patterns are exported:

| Import | Contents | | --------------------------------- | -------------------------------------------------------------- | | @cronos-labs/ui | The barrel — every component, token and helper below | | @cronos-labs/ui/<path> | Any single module, e.g. locale/config, locale/localization | | @cronos-labs/ui/eslint-config | createReactEslintConfig | | @cronos-labs/ui/prettier-config | The shared Prettier config, as a default export |

When to use a deep import instead of the barrel

This is the most common way to break a build. The barrel re-exports components that depend on react-router-dom and styled-components. Any context that evaluates modules with Node's own ESM loader rather than a bundler — an Astro config file, a content-collection schema, a sitemap script — cannot load it, and fails at import time with styled.div is not a function.

Reach for the single module you actually need in those places:

// astro.config.mjs — evaluated by Node, not the bundler
import { localeConfig } from '@cronos-labs/ui/locale/config';

// src/content/config.ts — content collection schema
import { Locale } from '@cronos-labs/ui/locale/localization';

Application code that goes through the bundler uses the barrel normally:

import { Header, Footer, tokens, useCurrentLocale } from '@cronos-labs/ui';

Bundler configuration

Vite treats the package as external during SSR by default and loads it with Node's native ESM loader, which does not apply the __esModule CJS-interop convention styled-components relies on. Force it through the same transform pipeline as styled-components itself:

// astro.config.mjs / vite.config.ts
ssr: {
  noExternal: ['styled-components', '@cronos-labs/ui'],
}

For Vitest, inline the package so component tests resolve it the same way:

test: {
  server: { deps: { inline: ['@cronos-labs/ui'] } },
}

What's in the package

Components

| Export | Purpose | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Header | Site header: brand wordmark, nav with dropdowns, mobile drawer, locale selector, waitlist CTA | | Footer | Site footer: link columns, legal links, cookie-preferences hook, disclaimer copy | | HeaderStatic / FooterStatic | Router-free variants for statically rendered pages (Astro). Take locale and pathname as props, force document navigation, and never import react-router-dom, so the island needs no <MemoryRouter> | | Seo | Renders nothing; imperatively upserts <title>, meta and canonical tags. Creates tags that are absent rather than skipping them | | LocaleSelector | Locale dropdown, shared by Header and Footer | | SectionAnchorNav | In-page anchor nav that tracks the active section | | SearchField | Labelled search input with optional clear button and status text | | PillButton, FilterPillRow | Filter pill primitives |

Header and Footer are driven entirely by props — no data fetching, no router coupling beyond react-router-dom. Their content strings arrive through HeaderContent / FooterContent so each app supplies its own localized copy.

Exported types: HeaderPresentationVariant, HeaderPresentationState, HeaderNavItem, HeaderNavChild, HeaderContent, HeaderWaitlistCta, FooterLinkItem, FooterLinkGroup, FooterLegalLinkItem, FooterContent, SeoMeta, RouteSeoMeta, SearchFieldProps, SectionAnchorNavItem.

Design tokens

tokens groups every shared value: colors, sizes, mediaQueries, borderRadius, fontWeight, typography, shadow, effects, motion, layout, zIndex. desktopViewportQuery is the min-width: 1024px media query the components use to switch to their desktop layout.

import { tokens, desktopViewportQuery } from '@cronos-labs/ui';

Typography

Ready-made styled-components css blocks, so type scale stays consistent across apps: displayHeroTitleTypography, pageHeroTitleTypography, articleHeroTitleTypography, sectionTitleTypography, articleSectionTitleTypography, cardTitleTypography, leadBodyTypography, articleBodyTypography, compactBodyTypography, eyebrowTypography, metaTypography.

Locale

Nine locales are supported: en, en-in, en-ng, en-ph, id-id, ko-kr, pt-br, es-mx, vi-vn. The prefix strategy is as-needed — the default locale has no path prefix, the rest do.

| Export | Purpose | | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | Locale | Enum of supported locale codes | | localeConfig | Full config: default, fallback, supported list, per-locale labels and text direction | | isSupportedLocale | Type guard for an unknown string | | resolveLocale | Resolves a value to a locale, falling back when unrecognised | | stripLocalePrefix | Removes the locale segment from a pathname | | buildLocalizedPath | Prefixes a path for a locale, honouring as-needed | | useCurrentLocale | Reads the active locale from the router | | useApplyLocaleDocumentAttributes | Keeps <html lang> and dir in sync | | setStoredLocalePreference, getStoredLocalePreference, hasStoredLocalePreference, localePreferenceStorageKey | Persisted locale preference (cronos.locale) |

Types: AppLocale, LocaleConfig, LocaleDefinition, LocalePrefixStrategy, TextDirection, LocalizedContentDictionary, LocalizedPageMetadata.

Utilities

| Export | Purpose | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------- | | navigationContent | Shared nav structure, with the NavigationContent type | | normalizePathname | Trailing-slash-insensitive pathname comparison used for nav active state | | interpolateMessageTemplate | Fills {placeholder} tokens in localized strings | | scrollToSectionHeading | Smooth-scrolls to a section's first h1/h2 (or [data-section-scroll-target]), offset 128px for the fixed header |

Shared lint and format config

// eslint.config.mjs
import { createReactEslintConfig } from '@cronos-labs/ui/eslint-config';

export default createReactEslintConfig({
  tsconfigRootDir: import.meta.dirname,
});

createReactEslintConfig takes tsconfigRootDir (required) and optional ignores and allowDefaultProject. It composes the recommended, type-checked and stylistic typescript-eslint sets with the React Hooks and React Refresh plugins, and disables rules Prettier owns.

// package.json
"prettier": "@cronos-labs/ui/prettier-config"

Local development

The toolchain is pinned, so every machine and CI resolve identically:

| Pinned by | File | Value | | --------- | ---------------------------------- | -------------------- | | Node | .nvmrc | 24.21.0 (active LTS) | | npm | packageManager in package.json | 11.19.0 |

Use a version manager that reads .nvmrc (nvm, fnm, asdf) and enable Corepack once — it ships with Node and resolves the npm named above.

This package deliberately publishes no engines field. The Node floor the dev toolchain needs comes from a dev dependency, not from anything the library does at runtime — it ships as bundled ESM and runs wherever its consumer runs. Publishing that floor would impose a constraint that is not real, and every consuming site sets engine-strict=true, so a wrong floor here would hard-fail their npm ci. Pin the toolchain for contributors, impose nothing on consumers.

nvm use          # or: fnm use
corepack enable
npm ci
npm run lint
npm run typecheck
npm run test
npm run build
npm run format:check

Use npm ci, not npm install, unless you are deliberately changing a dependency: packageManager fixes the npm version because two npm majors disagree about which optional peer entries belong in package-lock.json, and a lockfile written by one and installed by the other fails npm ci. The release workflow publishes with the same pinned npm.

build compiles src/ to dist/ with tsc, then rewrites every relative specifier in dist/**/*.js and dist/**/*.d.ts to point at the concrete emitted file. tsc emits extensionless specifiers under moduleResolution: "bundler", which plain Node ESM cannot resolve at runtime. dist/ is generated and not committed.

The repo formats itself with the same Prettier config it exports. A unit test asserts .prettierrc and src/config/prettierConfig.ts stay in sync, so the two copies cannot drift.

Structure rule

Styled React units use ComponentName/index.tsx for the component and ComponentName/styles.ts for its styled definitions.

Full-colour lockups in the Header

By default the Header draws one flat wordmark and applies filter: invert(1) on inverse surfaces. A coloured lockup cannot be inverted without shifting its colours, so pass both artworks instead: brandWordmarkSrc is the lockup for light surfaces and brandWordmarkInverseSrc the lockup for dark ones. The Header then shows the matching file for the current presentation variant and never inverts. The lockup is sized from layout.brandLogoMarkSize and aligned to the start of the brand column. Omit brandWordmarkInverseSrc to keep the previous behaviour.

Releasing

Releases are staged by tag and promoted by a human. The tarball is always built on the pinned runner rather than whatever happens to be on a laptop, and no credential in this repository can make a version live on its own: the CI token is a granular stage-only token, so the most it can do is put a build in front of a maintainer.

1. Land your change on main through a PR.

2. Bump version in package.json (semver).

3. Tag the merge commit and push:

   git tag ui-v<version>
   git push origin ui-v<version>

   The workflow refuses to continue if the tag and package.json disagree on the version. prepack rebuilds dist/ as part of packing, so a stale build cannot ship.

4. CI runs npm stage publish .. The version is now staged and not yet installable — npm view @cronos-labs/ui version still reports the previous release.

5. A maintainer with 2FA promotes it. The run log prints the stage id:

   npm stage list @cronos-labs/ui
   npm stage view <stage-id>       # inspect before shipping
   npm stage download <stage-id>   # or pull the tarball and check it
   npm stage approve <stage-id>    # publish
   npm stage reject <stage-id>     # discard

Consumers then bump their range and run npm install. A patch or minor inside their existing caret range needs no bump — npm install picks it up.

License

UNLICENSED. Published publicly on npm for installation convenience; not open source.