• See CHANGELOG.md for details on updates.

NPM Package 📦 – @muibook/components

Leverage reusable vanilla Web Components built with the Mui (MichaelUI) Design System in your project. Simply install the @muibook/components package to access a framework-agnostic, accessible, and customizable component library.

Usage Policy (Summary)

This repository is source-available for education and internal use. Redistribution, repackaging, or resale is not permitted. The intended public distribution channel is the NPM package: @muibook/components. See LICENSE for full terms.

npm install @muibook/components

Component Usage

import "@muibook/components"; // All
import "@muibook/components/mui-body"; // Individual

CSS Usage

import "@muibook/components/css/mui-brand.css";
import "@muibook/components/css/mui-tokens.css";
import "@muibook/components/css/mui-base.css";
import "@muibook/components/css/mui-reset.css";

Agent Usage

import "@muibook/components/agent/prompts";

For MCP-based agent context, use the exported knowledge repo at michaeltrilford/muibook-knowledge. After installing the Muibook knowledge MCP in a project that uses Muibook components, add an instruction like this to that project's AGENTS.md or equivalent agent guidance file:

When the Muibook MCP is available, call its `start_here` tool before answering questions or doing work about Muibook components, markup, styling, wrappers, dynamic attrs, knowledge, skills, or component documentation.

Knowledge Usage

The package also exposes Muibook knowledge for AI tooling and plugins:

import { knowledge } from "@muibook/components/knowledge";
import { rules } from "@muibook/components/knowledge/json-rules";
import { compositions } from "@muibook/components/knowledge/compositions";
import { keywords } from "@muibook/components/knowledge/keywords";

Generated metadata is published alongside the package:

@muibook/components/custom-elements.json
@muibook/components/dynamic-attrs.json
@muibook/components/AGENTS.md
@muibook/components/DESIGN.md

Links • npmjs.com • Docs • Usage • Components

Create Mui App

Kickstart your project with a lightweight scaffold built on Vite. It comes preloaded with foundational CSS resets, a solid base structure, and design tokens ready to be customised for your brand.

• ⚡ Vite-powered: Lightning-fast development with HMR
• 🎨 Pre-configured theming: Design tokens and CSS custom properties
• 🧱 Component showcase: Curated set of MUI Components in a clean layout
• 📱 Responsive foundation: Mobile-first CSS resets and utilities
• 🔧 Customisable: Easy to adapt for your brand and requirements

Learn more at Muibook.com

Muibook Repository

Muibook is the home of the MichaelUI Design System — native Web Components with clean, composable patterns that help you write less code.

• 📖 Comprehensive guides: From basic usage to advanced customization
• 🎨 Design principles: Learn the MichaelUI design language
• 🔧 API reference: Detailed documentation for every component
• 💡 Best practices: Proven patterns for scalable design systems

Learn more about Muibook.com

Start Development Server

This project is powered by Vite and uses TypeScript to provide a fast, modern development experience for building and previewing web components.

npm run dev

• Starts Vite in development mode
• Opens the app at http://localhost:5173 (or next available port)
• Supports hot module replacement (HMR) for fast feedback

Build Project

npm run build

• Compiles and bundles the project for production
• Outputs optimised files into the dist/ directory

Build Muibook

npm run build:muibook

• Builds the Muibook package using a custom Vite config (vite.muibook.config.ts)
• Produces a minified CSS and JS build for documentation

Preview Muibook Build

npm run preview:muibook

• Serves the minified Muibook build locally for previewing the compiled output

Build Create Mui App

npm run build:create-mui-app

• Builds the create-mui-app package using a custom Vite config (vite.create-mui-app.config.ts)
• Produces a minified CSS and JS build for documentation

Preview Create Mui App Build

npm run preview:create-mui-app

• Serves the minified create-mui-app build locally for previewing the compiled output

Setup

Install dependencies:

npm install

Clean install from the lockfile:

Use this when you want to install the exact dependency versions already recorded in package-lock.json, especially during an active NPM supply-chain issue.

npm ci
npm run build

• npm install reads package.json version ranges and may update package-lock.json.
• npm ci removes node_modules and installs exactly from package-lock.json.
• npm ci fails if package.json and package-lock.json are out of sync.
• Prefer npm ci for CI, release builds, and clean local verification.
• The current declared versions in package.json are pinned for now by removing ^ and ~ ranges.

TypeScript Support:

npm install --save-dev @types/node

VS Code Plug-in

Install es6-string-html for better HTML template literal syntax highlighting.

Style Dictionary

• npm run token-build

Knowledge Build

Muibook keeps authored AI knowledge in src/knowledge:

• json-rules.ts contains global component-tree generation rules.
• keywords.ts contains full keyword mappings and the curated local-agent keyword subset.
• compositions.ts contains full composition examples, curation metadata, and the generated local-agent composition subset.
• index.ts exports the combined knowledge object.

The full package build also generates and copies related knowledge files:

• public/custom-elements.json from component api.ts and doc.ts files.
• public/dynamic-attrs.json for runtime/destination structural attrs.
• root AGENTS.md and DESIGN.md.

npm run build syncs Muibook knowledge to two sibling destinations:

• npm run copy-knowledge copies the complete exported bundle into ../muibook-knowledge, which is published separately as michaeltrilford/muibook-knowledge for MCP clients and other AI tools.
• npm run copy-knowledge:redactd-canvas copies the Redactd-specific subset into ../RedactdCanvas/plugins/assets/muibook-knowledge for bundling with the Redactd Canvas plugin. This subset contains custom-elements.json, dynamic-attrs.json, DESIGN.md, json-rules.ts, and compositions.ts. keywords.ts stays in the MCP knowledge package only.

Muibook remains the source of truth for both exports. The destination copies should be regenerated rather than edited independently. Run the complete build to generate and sync both destinations:

npm run build

To refresh only one destination, run its copy command directly:

npm run copy-knowledge
npm run copy-knowledge:redactd-canvas

Use includeInAgent: true in compositionConfig only for compact examples that should be bundled into @muibook/components/agent/prompts. Keep richer examples in the full knowledge export with includeInAgent: false.

Publishing

Version Management

npm version patch  # Increment patch version
npm version minor  # Increment minor version
npm version major  # Increment major version

Test Before Publishing

npm pack --dry-run  # Preview what will be published

Publish to NPM

npm publish

NPM Token REFRESH

I have to login everytime it seems.

npm login tokens expire every 90 days When they do, you must log in again before publishing packages. No other setup needs to be repeated.

Steps:

1. Run npm login to refresh your token.
2. Publish normally with npm publish --access public
3. Repeat npm login every 90 days when prompted.

Development Notes

• Add any new components to vite.config.ts to include them in builds
• The dist/ folder is published, while source code and src/muibook are excluded
• Use the preview scripts to verify production builds before deployment
• Follow semantic versioning for releases

Adding new components

When adding new components, there are a couple of areas in the build we need to update.

1. vite.config.ts Add the new component’s entry point to the build configuration so it’s bundled into the final output.

2. package.json Ensure the new component is added to the exports field so it can be imported by consumers. If you’re using a files field, include the component path there too.

3. src/index.ts (Central export file) Add an export * from "./components/..."; line pointing to your new component’s file or directory. This makes it available through your library’s main entry point.

4. src/muibook/index.ts: (Demo Site) If the component relies on global styles or JS utilities for behavior or preview (e.g., for documentation or dev environments), make sure relevant styles or setup files are imported here.

🔍 Note: If the component uses an internal index.ts to re-export multiple parts (e.g., mui-icons/index.ts), you only need to reference the directory in your central export:

Slot Implementation Approach (MUI Design System)

When implementing slots in MUI components, we use a consistent approach for styling and interaction:

Children Concerns

• We use JavaScript to query and manage slotted elements.
• To apply styles to a slotted item, we append a class in the format: [parent-component]-slot.
• The slotted component detects this class via :host(.parent-component) and applies the relevant styles.

Parent Concerns

• If the parent component needs to react to the presence of a specific slotted item, we add an attribute like has-[slottedComponentName] to the host.
• The parent component can then target this via :host([has-slottedComponentName]) for conditional styling.

This method keeps slot behavior declarative and styles predictable across components.

License

• 
• MIT License - see LICENSE file for details.