@instruments/materia-ui 0.1.0

package/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2026 Material Instruments. All rights reserved.
+
+This software and its source code are proprietary to Material Instruments.
+No licence or other right to use, copy, modify, merge, publish, distribute,
+sublicense or sell this software, in whole or in part, is granted to anyone
+without the prior written agreement of Material Instruments. Making the
+software available for download does not grant any such right.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+MATERIAL INSTRUMENTS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE.
+
+Third-party material: the Inter typeface bundled at
+dist/styles/fonts/InterVariable.woff2 is licensed separately under the SIL
+Open Font License 1.1. Its terms are in dist/styles/fonts/OFL.txt and are not
+changed by this notice.

package/README.md

@@ -0,0 +1,216 @@
+# Materia UI
+
+The design system for prototypes in Material Bank's design language: React components, Tailwind v4 tokens, type, colour and motion in one package. An app built with it looks and behaves like the others.
+
+It carries Material Bank's brand by default and sits beside Material Bank's production component library. It doesn't replace it.
+
+## Install
+
+```sh
+pnpm add @instruments/materia-ui react react-dom motion tailwindcss @tailwindcss/postcss
+```
+
+React 19, Motion 13 and Tailwind v4 are required, and are peer dependencies. That line is for Next.js; with Vite, install `@tailwindcss/vite` in place of `@tailwindcss/postcss`. The package ships compiled ESM that loads under plain Node, so Next.js doesn't need `transpilePackages`.
+
+**Compatibility:** React 19.2+, Tailwind v4 only, ESM only, Node 22+. Next.js 15+ and Vite both work with no extra config.
+
+## Set up
+
+One CSS import, after Tailwind's own:
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@import "@instruments/materia-ui/styles";
+```
+
+That one import brings the colour, radius, type, shadow and motion tokens, the Inter variable font, and registers the package's classes with Tailwind. There's no Tailwind config file to write.
+
+**Styling weight:** JavaScript tree-shakes per import, but the stylesheet's `@source` lines register the whole kit's class vocabulary. Your Tailwind output therefore includes every component's utilities, whatever you import (about 430 kB of uncompressed CSS in a minimal Next.js app). There's no lighter entry point yet.
+
+One provider, at the root:
+
+```tsx
+import { ReducedMotionProvider } from "@instruments/materia-ui/components/motion-config";
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <ReducedMotionProvider>{children}</ReducedMotionProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+It loads the animation features once and honours the reader's reduced-motion setting.
+
+## Use
+
+Every component has its own import path. There's no root barrel, so you bundle only what you import.
+
+```tsx
+import { Button } from "@instruments/materia-ui/components/button";
+import { ProductCard } from "@instruments/materia-ui/compositions/product-card";
+```
+
+| Path | What's there |
+| --- | --- |
+| `/components/*` | Components: primitives and primitive-like pieces such as buttons, dialogs, menus and form controls. One job each, generic content, nothing about materials or a catalogue. |
+| `/compositions/*` | Compositions: larger constructions that assemble components into a page region or feature, such as the sidebar, the data grid and the product card. You pass the data and the actions. |
+| `/tokens`, `/tokens/*` | Tokens as TypeScript: sizes, tones, radii, shadows, motion. |
+| `/hooks/*`, `/utils/*` | Supporting hooks and helpers, `cn` among them. |
+| `/icons` | The icon set. |
+| `/data/*` | Reference data, including `docs-manifest`: a machine-readable description of every component's props and usage, for tooling and AI agents. |
+| `/styles` | The stylesheet. |
+
+Components don't know about materials or a catalogue. Compositions, such as the sidebar, the data grid and the product card, assemble components into a page region or feature: they receive all their data and actions from your app and fetch nothing themselves.
+
+### Prop vocabulary
+
+Controls that carry colour (`Button`, `Pill`, `Tag`, `Badge`, `IconBox`, `Kbd`) take `tone` and `emphasis`; `Alert` takes `tone` alone. Components that only change appearance (`Card`, `Toggle`, `Accordion`, `Item`, `Anchor`) take a single `variant`. `size` is reserved for the size scale; a width mode is named `width`.
+
+### Composing with `render`
+
+Components are built on [Base UI](https://base-ui.com). To render a component as another element, pass `render`. There's no `asChild`.
+
+```tsx
+<Button render={<a href="/projects" />}>Projects</Button>
+```
+
+### Dark mode
+
+Dark mode is class-based: put `dark` on `<html>`. Any theme switcher that toggles a class works, `next-themes` included.
+
+### Your own brand
+
+The brand is four CSS variables. Set them after the stylesheet import:
+
+```css
+:root {
+  --color-brand: #0f62fe;
+  --color-brand-soft: #d0e2ff;
+  --color-brand-accent: #0043ce;
+  --color-brand-foreground: #ffffff;
+}
+```
+
+The logo takes your own mark and name:
+
+```tsx
+<Logo mark={<MyMark />} label="My product" />
+```
+
+The brand variables are the supported override. Other CSS variables in the stylesheet are internal: they aren't a contract and may change between releases.
+
+### Patterns, not components
+
+Some things are compositions of what's here rather than components of their own. A date picker is `Calendar` inside `Popover`. Forms are built from the `Field` primitives.
+
+### Location search
+
+`LocationInput` is a finished autocomplete for city or address search, but it ships no geocoder. Pass it `search` and `resolve` functions backed by whichever service you use.
+
+### Agents
+
+The package ships two things for coding agents:
+
+- `agent-docs.md`: do and don't guidance for every component, headed by a short set of rules. It's at `node_modules/@instruments/materia-ui/agent-docs.md`.
+- `@instruments/materia-ui/data/docs-manifest`: a structured description of every component, its props and its usage, for tools.
+
+Point your agent at the guidance from your own `AGENTS.md` or `CLAUDE.md`:
+
+```md
+## UI
+Build UI with @instruments/materia-ui. Before writing any UI, read
+node_modules/@instruments/materia-ui/agent-docs.md and follow its rules.
+Never invent a prop; if a component can't do what you need, say so.
+Run `materia-ui-lint --all <dirs>` on what you changed.
+```
+
+## Build an app
+
+The sidebar follows shadcn's: `SidebarProvider`, `Sidebar`, `SidebarInset`, the same part names and props, so anyone who knows shadcn's sidebar already knows this one. The one naming difference is `isActive`, which is `active` here. Split it into `AppSidebar`, `NavMain` and `NavUser` as shadcn's blocks do.
+
+```tsx
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarHeader,
+  SidebarInset,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarProvider,
+  SidebarRail,
+  SidebarTrigger,
+} from "@instruments/materia-ui/compositions/sidebar";
+
+<SidebarProvider defaultOpen={defaultOpen}>
+  <Sidebar collapsible="icon">
+    <SidebarHeader>
+      <TeamSwitcher />
+    </SidebarHeader>
+    <SidebarContent>
+      <SidebarGroup>
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton
+              active
+              icon={FolderKanban}
+              tooltip="Projects"
+              render={<Link href="/projects" />}
+            >
+              Projects
+            </SidebarMenuButton>
+          </SidebarMenuItem>
+        </SidebarMenu>
+      </SidebarGroup>
+    </SidebarContent>
+    <SidebarFooter>
+      <NavUser />
+    </SidebarFooter>
+    <SidebarRail />
+  </Sidebar>
+  <SidebarInset>
+    <header>
+      <SidebarTrigger /> <Breadcrumbs />
+    </header>
+    {children}
+  </SidebarInset>
+</SidebarProvider>;
+```
+
+Cmd/Ctrl+B toggles it, and below `md` it opens as a sheet. `SidebarInset` is the content column and the page's single `<main>`; the provider renders a skip link to it first (`skipLink={false}` to opt out). The open state lives in a `sidebar_state` cookie (the `document.cookie` fallback covers browsers without the Cookie Store API); read it on the server and pass it as `defaultOpen`, or control it with `open` and `onOpenChange`.
+
+- `height="fill"` on the provider pins the frame to the viewport and lets the inset scroll internally; the default `"auto"` lets the page scroll.
+- `SidebarPanel` beside the inset adds a docked right-hand panel (`open`, `side`, `width`).
+
+### Coming from Materia's packages/ui
+
+There is one way to build a frame. `AppShell` is gone.
+
+| Was | Now |
+| --- | --- |
+| `AppShell` | `SidebarProvider` |
+| `AppShellBody`, `AppShellMain` | `SidebarInset` |
+| `AppShellHeader` | a plain `<header>` inside the inset |
+| `AppShellPanel` | `SidebarPanel` |
+| `AppShellSkipLink` | built into `SidebarProvider` |
+| `SidepanelContent` `size` (`"default" \| "full"`), type `SidepanelSize` | `width`, type `SidepanelWidth` |
+| `Swatch` `shape` prop | `kind` (`data-shape` is `data-kind`) |
+| `VARIANT_DIMENSIONS` `"color_name"` | `"colorName"` |
+| `VARIANT_DIMENSIONS` `"product_finish_type"` | `"finishType"` |
+| `ProductCard` `productUrlPattern` (a closed set of route patterns) | `productUrl`, a function from product to href |
+| `ProductCardProduct` `materialBankId`, `projectSaveCapability`, `projectSpecification`, `sourceStatus`, `slugBasis` | removed; carry them in `payload`, which the card never reads |
+
+## Licence
+
+All rights reserved. No use, copying or redistribution without written agreement from Material Instruments; see `LICENSE`. Inter is bundled under the SIL Open Font License.