Forge Design System

CSS-first design system for reusable operational interfaces across native HTML, vanilla JavaScript, Web Components, TypeScript consumers, and non-web platform adapters.

Forge is intentionally platform-native:

• CSS classes are the source of truth.
• Native HTML is the default adoption path.
• Web Components are optional enhancements.
• TypeScript support is provided through declarations for the framework-neutral JavaScript API.
• Framework adapters belong in product apps and should wrap Forge classes, recipes, tokens, and icon names.

No component should require JavaScript for its baseline visual rendering.

Install

npm install @pietropecchi/forge-design-system

Or copy the folders you need directly into a project:

css/
core/
elements/

CSS-First Use

Load the stylesheet and use native HTML:

<link rel="stylesheet" href="./css/forge.css">

<section class="forge-panel">
  <div class="forge-section-title">
    <p class="forge-section-title__eyebrow">Workspace</p>
    <h2 class="forge-section-title__heading">Open work</h2>
  </div>

  <p class="forge-inline-notice">Attach evidence before closing the task.</p>
  <button class="forge-button forge-button--primary" type="button">
    Open task
  </button>
</section>

For forms, tables, buttons inside forms, and highly semantic layouts, prefer native HTML with Forge CSS classes.

JavaScript Recipes

The package default export is side-effect free, typed for TypeScript consumers, and does not register custom elements:

import { button, buttonRecipe } from '@pietropecchi/forge-design-system';

const className = button({ variant: 'secondary', size: 'sm' });
const compatibleClassName = buttonRecipe({ variant: 'secondary', size: 'sm' });

Optional Web Components

Use Web Components for behavior-heavy enhancement primitives. Baseline markup stays light DOM and themeable from the stylesheet:

<link rel="stylesheet" href="./css/forge.css">
<script type="module" src="./elements/auto.js"></script>

<forge-popover>
  <button class="forge-button forge-button--secondary" type="button">
    Filters
  </button>
  <div data-forge-popover-panel>
    Status, owner, and date filters.
  </div>
</forge-popover>

Existing simple custom elements remain available as compatibility adapters, but new buttons, cards, forms, tables, typography, and layout should use native HTML with Forge classes.

Package Exports

• @pietropecchi/forge-design-system: side-effect-free class recipes.
• @pietropecchi/forge-design-system/css: canonical CSS.
• @pietropecchi/forge-design-system/icons: semantic icon catalog for adapters.
• @pietropecchi/forge-design-system/icons.json: portable icon catalog for non-JS tooling.
• @pietropecchi/forge-design-system/tokens: JavaScript token map.
• @pietropecchi/forge-design-system/tokens.json: portable design tokens for non-JS tooling.
• @pietropecchi/forge-design-system/recipes: class recipe helpers.
• @pietropecchi/forge-design-system/elements: optional Web Component definitions.
• @pietropecchi/forge-design-system/auto: auto-register optional Web Components.
• @pietropecchi/forge-design-system/custom-elements.json: machine-readable Web Component contract.

Platform Contract

Forge is not a React, Vue, Flutter, or Python component library. It is a shared design contract:

• web apps consume CSS classes directly, with recipes where class composition is useful;
• React, Vue, Svelte, and TypeScript apps build thin local components on top of the same CSS classes;
• Flutter, Python, and automation tooling can consume core/tokens.json and core/icons.json as portable references;
• adapters must not become a dependency of the core package.

Keep framework adapters local to the product. A React, Vue, Svelte, or native app wrapper should be a thin layer over Forge classes, recipes, tokens, and semantic icon names, not a second component contract that ships from Forge.

Release Confidence

The published package ships one installed-package smoke test:

npm test

Run that command from an installed or packed copy of Forge to verify the npm package contract without requiring the source repository test files.

Repository releases use the fuller gate from the source checkout:

npm run test:release
npm pack --dry-run

The repository-only scripts test:contract, test:visual, and test:release expect the source checkout because tests/ is not shipped in the npm tarball.

css/forge.css has an 80 KiB raw size budget, and the visual smoke path checks the homepage, manual, and vanilla business-app example.

Documentation

• Adoption Guide
• API Contract
• Browser Support
• Component Catalog
• Design Rules
• Iconography
• Platform Contract
• Release Policy
• Visual Verification
• Changelog
• HTML Manual

Examples

• Homepage showcase: the root documentation/showcase page.
• HTML manual: a user-friendly guide that renders the Markdown documentation as real Forge UI examples.
• Vanilla integration example: a minimal native HTML page that exercises the CSS classes and optional Web Components in an app-like layout.