Build with Martlet.

The UI language beyond the package reference

The source audit, experimental grammar, contents/sidebar distinction, independent footer anatomy, interaction obligations and framework support now have a consolidated language reference. Core 2.2.1 and Astro 1.2.1 are experimental releases under the npm next tag; the package versions reported on this page remain the exact installed releases.

Choose what to adopt

For colors or styles in any web project, install the core. Add the Astro package when you want its reusable components.

npm install @martlet/theme

import '@martlet/theme/full.css';
import '@martlet/theme/fonts.css';

<section class="martlet" data-martlet="dark">
  <h2>Your content</h2>
</section>

Color scopes can coexist on a page. Add class="martlet" to opt into typography and component styling. The core also exports ESM, CommonJS, TypeScript declarations, per-mode JSON, and highlight.js styles. The color reference shows both semantic palettes. Use purpose-based roles such as --martlet-text, --martlet-bg, and --martlet-on-accent together; source colors and semantic roles serve different purposes.

Typography

Display and serif are separate roles even where they use the same family. Monospace changes affect code and terminal roles. Optional font loading uses locally bundled open-source assets; Berkeley Mono is a personal licensed override and is not distributed.

Foundation tokens

These are the installed core’s exact defaults, including text sizes, line heights, spacing, widths, corners, shadows, focus dimensions, and motion. Responsive expressions are preserved as CSS values. Breakpoint tokens, where present, document the scale; ordinary CSS custom properties cannot be substituted directly into media-query conditions.

Source provenance: k3jph/k3jph.github.io at 471abfe. The JSON specification also includes grouped design definitions, both semantic color modes, and host capabilities.

Astro components and starter

The installed wrapper supports astro ^5.14.0 || ^6.0.0 || ^7.0.0 with @martlet/theme ^2.2.1. Install both peer packages in an existing Astro project:

npm install @martlet/theme @martlet/astro

---
import { Layout, Container, SectionHeading, Card, Button } from '@martlet/astro';
---
<Layout title="Your website" mode="light">
  <Container width="reading">
    <h1>Your own identity</h1>
    <SectionHeading title="Start here" />
    <Card>
      <p>Your content, using shared design definitions.</p>
      <Button href="/about/">About</Button>
    </Card>
  </Container>
</Layout>

Import components from @martlet/astro or use direct paths such as @martlet/astro/Card.astro. To retain your own document shell, import @martlet/astro/styles.css and apply the core’s class and appearance attributes.

Start a new site

The npm package includes a neutral starter/ directory. From an existing project or a temporary setup directory, install the packages and copy the starter to a new directory. The example below uses a POSIX shell; other systems can copy the same folder with their file manager.

npm install @martlet/theme @martlet/astro
cp -R node_modules/@martlet/astro/starter ./my-martlet-site
cd my-martlet-site
npm install
npm run dev

The starter currently uses Astro 7, so use Node 24 or another runtime supported by that Astro release. The starter supplies initial files; the packages supply updates afterward. Replace the sample content and metadata with your own.

Interaction and accessibility

The optional core components provide hover, disabled, and visible keyboard-focus styling. Motion tokens reduce to zero when prefers-reduced-motion: reduce is active. Use native links for navigation and native buttons for actions; retain labels, heading order, and the document skip link.

Pair foreground and background tokens deliberately. Existing contrast checks cover defined pairs, not every possible combination or application. Check normal, hover, focus, and disabled states in both appearances, with enlarged text, narrow viewports, keyboard navigation, and reduced motion. Use labels or symbols as well as color to communicate status.

Layouts and components supply primitives. Menus, dialogs, consent controls, analytics, and their behavior remain the responsibility of the consuming site. A themed page still needs application-level accessibility review.

What each integration applies

Browser themes apply browser interface colors. Editor and terminal ports map the roles their hosts support. They do not all reproduce a web layout or change typography automatically.

Customization and releases

Override namespaced variables within your own site scope, loaded after the package styles. This changes your installation without creating another authoritative copy of the theme.

.my-site {
  --martlet-reading-width: 44rem;
  --martlet-font-mono: 'Your licensed font', monospace;
}

The core and Astro packages are versioned independently. The release policy is semantic versioning: compatible fixes are patches, compatible additions are minor releases, and breaking changes to exports, tokens, component APIs, or documented behavior require a major release. Keep a lockfile and review updates against your application. This website pins the versions shown above; the reference changes when those pins change.

Propose shared visual changes in the core repository, with corresponding documentation and verification. Theme software uses the MIT license; fonts retain their bundled license notices. Heraldic artwork, personal identity, and site content are separate from the reusable design system.