Foundry41 UI Foundation

@mj-ps-2026/design-system is the shared, versioned UI foundation for Foundry41 products. It is intentionally boring.

The package does not try to be a bespoke component library. Its job is to make ordinary application UI cheap, accessible, themeable, and consistent while keeping Product code independent of the underlying implementation libraries.

Architecture

The supported dependency direction is:

native HTML / Radix Primitives -> thin adapters + generic layout -> semantic theme -> Product

• Native HTML owns ordinary controls where the platform is sufficient.
• Radix Primitives owns difficult interaction behavior such as dialogs, tabs, tooltips, and switches.
• This package owns the stable Product-facing adapter API, semantic theme contract, generic layout primitives, shared CSS, and a small number of compatibility helpers.
• Products own information architecture and behavior.
• The Foundry41 appearance is one theme, not component structure.

Products never import Radix directly as a substitute for the package API. That keeps the underlying library replaceable without forcing coordinated Product rewrites.

White-label contract

White-labeling is structural. Compatible themes use the same --ds-* semantic keys and change brand expression without changing Product markup.

src/themes/foundry41.json is the canonical machine-readable theme shape. src/themes/foundry41.css is the Foundry41 implementation of that shape. Customer themes use the same keys. There is no second public palette/reference-token vocabulary.

The theme controls typography, surfaces, text roles, action colors, borders, status colors, focus treatment, motion, elevation, and geometry intended to vary by brand. Layout and component behavior remain stable.

Foundry41 default theme

• Archivo for body/display/wordmark roles.
• JetBrains Mono for mono/label roles.
• Warm neutral surfaces with a restrained orange accent.
• Lucide icons at the declared defaults.
• Compact geometry, restrained elevation, mechanical motion.

These are values assigned to the shared semantic roles, not a separate Foundry-specific token language.

The package self-hosts the canonical Archivo and JetBrains Mono faces through Fontsource dependencies. Products do not need a Google Fonts request or Product-local font workaround.

Generic layout

The React API includes deliberately generic structural helpers such as AppShell, Page, Stack, Grid, Panel, SplitView, and ChatPanel. Conversational surfaces can use ChatMessage, TypingIndicator, and ChatComposer for ordinary assistant/user/waiting/composer presentation without adopting a second chat runtime or styling system. These helpers own responsive geometry and semantic styling, not a distinctive Foundry41 visual composition.

Structured data inside a conversational experience should continue to use ordinary semantic controls such as Field and Input, preserving browser autofill, appropriate mobile keyboards, and native accessibility rather than forcing every value through a generic chat text box.

Legacy reusable helpers such as PageHeader, FormSection, EmptyState, and DetailList remain available while Products migrate toward the thinner layout model. ApplicationShell is a compatibility alias for AppShell.

Email surfaces

Transactional email is a Design System surface even when an external provider renders or sends it. @mj-ps-2026/design-system/email exposes an email-safe resolved projection of the semantic theme plus a generic document frame and status treatment for clients that cannot load CSS variables, package fonts, or application stylesheets.

Products continue to own message purpose, copy, data, sender identity, and destinations. Providers own transport only. Provider-managed templates must be kept under version control and reconciled from canonical Product sources rather than treated as an ungoverned visual exception. See docs/email.md.

Development

npm install
npm run check

npm run check builds the package and catalog, checks the visual contract, and runs the repository tests.

Usage

npm install @mj-ps-2026/design-system@<version>

Import the complete stylesheet once:

import "@mj-ps-2026/design-system/styles.css";

Then consume the package boundary:

import { AppShell, Page, Panel, Button, Field, Input, Dialog, Tabs } from "@mj-ps-2026/design-system/react";

Do not copy component CSS or build a parallel token vocabulary inside Product repositories.

Operation

Release and consumer operations are versioned and explicit. Run npm run check before proposing a release; GitHub Releases drive npm trusted publication; Products adopt a published package through reviewed dependency upgrades rather than mutable source synchronization. The canonical release and package procedures live in docs/api.md and docs/runbook.md.

The scoped npm coordinate is a release invariant; any change requires an explicit migration plan.

Visual constraints

Foundry41-owned UI remains intentionally restrained. Gradients, glass effects, ornamental icon use, spring/bounce motion, and left-edge accent rails are outside the default theme. White-label themes may change brand expression while preserving the semantic and accessibility contract.