Martlet core

Unpublished migration candidate: @martlet/core is a proposed new package identity, not an announced registry release. Install the local tarball to test it. Existing @martlet/theme installations remain the supported published path until a separately approved release and migration. This review branch is marked private to prevent publication.

@martlet/core is the framework-independent source of truth for Martlet. It contains Light/Dark semantic colors and the typography, spacing, shape, depth, and interaction definitions extracted from jameshoward.us.

Design direction

For the design direction and criteria for expanding the system, read the Martlet design charter.

Choose what to adopt

import '@martlet/core/full.css';
import '@martlet/core/fonts.css';
import { light, dark, foundation, design, capabilities } from '@martlet/core';

Set data-martlet="light" or data-martlet="dark" on the element to theme; add class="martlet" to opt into typography and interface styling. Modes may coexist on the same page. CSS remains available without JavaScript; font package imports require a CSS-capable bundler. ESM and CommonJS exports, TypeScript declarations, per-mode JSON, tokens.json, foundation.json, design.json, capabilities.json, and highlight.js styles are explicit package exports.

Typography and overrides

• Serif: Cambo, for prose and primary headings.
• Sans: Lato, for interface text, navigation, and metadata.
• Display: Cinzel, for display accents and secondary heading roles.
• Monospace: IBM Plex Mono, for code and terminal text.

These roles come from the originating personal site, not the demonstration site's former Space Grotesk/DM Sans pairing. Berkeley Mono is not distributed. An owner who has licensed it can override --martlet-font-mono on their own root or theme scope. Generic consumers need no proprietary fonts. See NOTICE.md for font licenses.

The optional full stylesheet is not a site template: it includes no personal identity, content, analytics, or consent policy. See @martlet/astro for Astro composition and a neutral starter.

Source and releases

Edit source.json here; run npm ci --ignore-scripts, npm run build, npm test, and npm pack. Generated dist/ is committed for review and reproducibility. Fontsource dependencies are pinned; lockfiles retain their integrity. The source website's original colors are retained as separate identity tokens rather than silently replacing existing semantic app colors. Reduced-motion preferences zero the shared motion tokens.

The capabilities export records what each integration applies, requires separate configuration for, or cannot support. A browser color theme does not change fonts. Editors and terminals use the monospace role only where their host allows it.

The npm scope is martlet. To test this candidate, run npm pack and install the resulting local tarball. Published consumers continue to use @martlet/theme. Package versions are independent of application-port versions.

Application port generators in martletdesign/martlettheme currently consume @martlet/theme. Their migration requires a separate reviewed change. Ordinary verification does not publish; publishing a GitHub release triggers the release workflow.

Layouts

Version 2.1 adds optional layout.css, the layout JavaScript export, and layout.json. Layout primitives cover containers, vertical stacks, wrapping clusters, bounded grids, sidebars, and paired regions. Import @martlet/core/full.css for the complete styling layer or add @martlet/core/layout.css after foundation.css for structural classes alone. See source observations and responsive rules.

Releases

The current GitHub release workflow can publish automatically through npm trusted publishing; this private candidate cannot be published. See release setup for the one-time package authorization and release order.

Foundations specification

Read the working foundations specification for spacing relationships, responsive composition, typography, density, surfaces, motion, accessibility, and the distinction between shipped values and proposed application roles.

Experimental UI language

Grammar, source decisions, framework and migration guide, and machine-readable support describe the experimental core 2.2.2 / Astro 1.2.2 consolidation. Existing defaults remain compatible; the source profile is opt-in.

Grammar coverage review, validated forms, and query/results patterns extend the experimental grammar to 0.3.

Adoption repair preview

The existing @martlet/theme@next is the experimental 2.2.2 line; latest remains the stable 2.1 line. Package, grammar and framework versions are separate: grammar 0.3 is the design contract, core 2.2.2 supplies CSS/tokens, Astro 1.2.2 supplies wrappers, and React 0.1.0 retains its tested core 2.1.0 dependency. Exact package versions belong in the lockfile.

Direct HTML anatomy documents layout/pattern classes. Native form styling documents the optional forms.css layer included in full.css; behavior remains host-owned. Existing colors/fonts and marks retain their native identity.