@nanisoft/prism-llms 0.4.0 → 0.5.0

package/dist/md/foundation/shadows.md

@@ -0,0 +1,9 @@
+# Shadows
+
+Exactly three authored elevation steps, all mode-independent.
+
+Elevation is authored, not borrowed. There are three shadow steps, all black
+alpha with a real vertical offset and a soft blur. `xs` sits under a filled
+control, `sm` under a card, and `md` under the one element that means lifted.
+
+<TokenTable group="shadow" />

package/dist/md/foundation/spacings.md

@@ -0,0 +1,8 @@
+# Spacings
+
+The authored spacing scale both layout and section rhythm use.
+
+Spacing is authored once and reaches CSS as `--spacing` and its steps. `Section`
+owns the page rhythm, and a gutter is a spacing token rather than a literal.
+
+<TokenTable group="spacing" />

package/dist/md/foundation/typography.md

@@ -0,0 +1,9 @@
+# Typography
+
+Inter for the interface, the platform monospace stack for machine values.
+
+Inter is the one interface face. The platform monospace stack annotates
+machine-readable values. Sizes are authored as size and line-height pairs, and
+leading, tracking and weight are authored tokens too.
+
+<TokenTable group="typography" />

package/dist/md/foundation/variables.md

@@ -0,0 +1,9 @@
+# Variables
+
+The full token browser: every semantic custom property and every foundation group.
+
+This is the token inventory. It reads the emitted JSON rather than a hardcoded
+table, so it is the same data the stylesheet is compiled from. Colours are shown
+as light and dark pairs; the mode-independent groups are shown once.
+
+<TokenBrowser />

package/dist/md/overview/architecture.md

@@ -0,0 +1,76 @@
+# Architecture
+
+How Prism keeps tokens, the component library, the docs site and the agent surface on one source of truth.
+
+Prism is owned source. It uses Base UI for accessible interaction behavior
+internally, then applies its own props, anatomy, tokens and composition
+patterns. None of the internal dependency is public API.
+
+## The package boundary
+
+`@nanisoft/prism-ui` is the only UI package an application imports. It ships
+compiled JavaScript and declarations, and its `exports` map is the public
+surface. The token package, `@nanisoft/prism-tokens`, is a pure data package;
+you normally do not import it directly because the compiled CSS reaches you
+through the one stylesheet.
+
+That boundary gives a consuming project three guarantees:
+
+1. No direct dependency on a second component library.
+2. No upstream visual defaults leaking into your product.
+3. One version line for behavior, design, documentation and machine-readable
+   source.
+
+## Three composition layers
+
+- **Component**: a focused, accessible, product-agnostic export with one job.
+  Compound parts, such as the pieces of a card, stay inside the parent module.
+- **Block**: a pre-composed, product-agnostic section assembled from Components.
+  It takes its content as props and fetches nothing.
+- **Page**: a complete structural composition of Blocks and Components that
+  models a whole screen and receives application-owned data.
+
+The dependency direction is one-way. Sibling layers do not import each other,
+and shared UI moves downward.
+
+```text
+Pages -> Blocks -> Components -> semantic tokens
+```
+
+## The catalogue
+
+The catalogue is one checked module, `packages/ui/src/catalog.ts`, exposed as
+`@nanisoft/prism-ui/catalog`. It is the only list. Navigation, the generated
+item documentation, the corpus and the agent surface all consume it, and none
+keeps a second list. An entry carries the item's name, slug, kind, category,
+description, source, public exports and status.
+
+The internal shadcn registry is derived from, or validated against, the
+catalogue. It is an integrity artifact and is never a public install lane.
+
+## The styling contract
+
+Prism ships one precompiled stylesheet and semantic custom properties. A
+component consumes semantic utilities only (`bg-background`,
+`text-muted-foreground`), never a ramp step and never a raw value. Because the
+semantic names are shadcn's variable contract, an unmodified shadcn block or
+theme works against the packs with no rename.
+
+There is no override path. A consumer composes, passes content and data, and
+chooses a pack and a mode. When Prism lacks something, it is requested upstream
+rather than patched locally.
+
+## Source to corpus
+
+The corpus is a deterministic projection of the same inputs the site renders:
+
+```text
+catalogue + emitted declarations + authored MDX + demo sources
+                            |
+                            v
+        llms.txt, the Markdown mirror, and the MCP store
+```
+
+The agent surface and the documentation site therefore cannot disagree about
+what an item is: both read the catalogue, the types and the same demo files.
+The detailed pipeline is in [Using LLMs](/overview/using-llms).

package/dist/md/overview/brand.md

@@ -0,0 +1,41 @@
+# Brand policy
+
+What the MIT licence covers, what it does not, and how the Prism and NaniSoft names may be used.
+
+The Prism packages are MIT-licensed, copyright NaniSoft, 2026. The code is yours
+to use, study, modify and redistribute, including commercially. Attribution and
+third-party notices live in the repository's `THIRD-PARTY-NOTICES.md`.
+
+A code licence grants rights in the code. It does not grant rights in the brand,
+and this page, not the licence, is where the brand rules live.
+
+## What is ours
+
+The names **Prism** and **NaniSoft**, the Prism wordmark, and the six pack names
+(`default`, `blush`, `mint`, `lavender`, `sky` and `peach`) identify Prism as
+built by NaniSoft.
+
+## What you may do
+
+- Say, accurately, that your product is *built with* Prism, and link here.
+- Fork, modify and redistribute the code under MIT, including shipping your own
+  packs, as long as you do not present the result as Prism or as originating
+  from or endorsed by NaniSoft.
+- Reference Prism in prose, talks and comparisons to identify the project, the
+  way any trademark is used to name the thing it names.
+
+## What you may not do
+
+- Distribute a modified or repackaged version under the Prism or NaniSoft names,
+  or with the Prism wordmark.
+- Use the names or the wordmark as your product, domain or package name, or in a
+  way that implies NaniSoft endorsement or certification.
+
+## Status
+
+These marks are not registered, and they are protected by the licence's honesty
+and by common-law rights. If you are unsure whether a use is fine, ask before
+you ship, and if you spot a use of the brand that looks off, tell us.
+
+A pack of your own is welcome and encouraged. It needs its own name: the six
+pack names identify Prism, so a fork's palette takes a new one.

package/dist/md/overview/composition.md

@@ -0,0 +1,77 @@
+# Composition
+
+Choose the smallest Prism layer that owns the job, and promote repetition upward only when it earns it.
+
+Prism's three layers answer three different questions. The skill is starting at
+the bottom and moving up only when the product asks for it.
+
+## Start with a Component
+
+Reach for a Component when the product needs one accessible control or one
+visual responsibility.
+
+```tsx
+import { Button } from '@nanisoft/prism-ui/components/button'
+
+<Button onClick={save}>Save changes</Button>
+```
+
+Do not build a local button variant when the action differs only by consequence.
+The `variant` prop already encodes the action hierarchy, and a local variant is
+the start of a second design system.
+
+## Promote repetition into a Block
+
+A Block earns its place when the same section appears across routes or products.
+It is pre-composed and product-agnostic, so the copy and the data stay at your
+call site.
+
+```tsx
+import { Stats01 } from '@nanisoft/prism-ui/blocks/stats-01'
+
+<Stats01
+  title="This month"
+  stats={[
+    { label: 'Active projects', value: '1,284', delta: 12, hint: 'vs last month' },
+    { label: 'On track', value: '47.2%', delta: -3, hint: 'vs last month' },
+  ]}
+/>
+```
+
+Good Block candidates are sections that repeat: a hero, a metric row, a pricing
+comparison, a closing call to action. A section that appears once is a local
+composition, not a Block.
+
+## Compose a Page last
+
+A Page coordinates regions and a whole screen. It does not recreate component
+behavior; it arranges what the lower layers already own.
+
+```tsx
+import { Pricing01 } from '@nanisoft/prism-ui/blocks/pricing-01'
+
+export function Plans() {
+  return (
+    <Pricing01
+      title="Pick a plan"
+      plans={plans}
+    />
+  )
+}
+```
+
+## The composition rules
+
+- Dependencies point downward: Pages, then Blocks, then Components.
+- Keep behavior in the lowest layer that owns it.
+- Keep brand colour in tokens, not in page CSS.
+- Keep application data and routing in the application.
+- Prefer a documented prop over a chain of local class overrides.
+- Pass the heading level explicitly when a Block is the page's top-level
+  heading, and leave it at its default when a Block is composed under one.
+
+## Where to go next
+
+- Browse the [Components](/components) for the controls.
+- Browse the [Blocks](/blocks) for the sections.
+- Read [Theming](/overview/theming) before restyling anything.

package/dist/md/overview/quickstart.md

@@ -0,0 +1,97 @@
+# Quickstart
+
+Install Prism, load one stylesheet, choose a pack, and render your first Component and Block.
+
+Prism is one npm boundary for tokens, components, blocks and pages. This guide
+takes you from an empty project to a rendered block, and it names the one
+stylesheet and the two attributes that do the theming.
+
+## Install
+
+```sh
+npm install @nanisoft/prism-ui
+```
+
+React stays your application's dependency. Prism's Base UI runtime and Tailwind
+are internal dependencies of the package; you install neither, and you import
+neither.
+
+## Load the one stylesheet
+
+Import Prism's stylesheet once, beside your own global CSS. It carries the token
+custom properties, all six packs, both modes, and every utility the components
+use.
+
+```ts
+import '@nanisoft/prism-ui/styles.css'
+import './globals.css'
+```
+
+If your project uses Tailwind, Prism's stylesheet is still a separate import.
+Prism is not a Tailwind plugin, and it is not merged into your Tailwind build.
+
+## Choose a pack and a mode
+
+Theming is two markup attributes, and it works without JavaScript. `data-pack`
+selects the palette, and the `dark` class selects the mode. The neutral base
+pack is the absence of `data-pack`.
+
+```tsx
+// app/layout.tsx
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" data-pack="lavender">
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+
+To persist a choice and switch at runtime, mount `PrismProvider` and use
+`usePrismTheme`. The provider is optional; the declarative attributes above need
+no client runtime. See [Theming](/overview/theming) for the full model.
+
+## Render the first Component
+
+```tsx
+import { Button } from '@nanisoft/prism-ui/components/button'
+
+export function SaveAction() {
+  return <Button onClick={save}>Save changes</Button>
+}
+```
+
+A component is imported from its own subpath. The curated root barrel
+(`@nanisoft/prism-ui`) is convenient for an app that uses most of the set, but a
+single import is the smaller pull. The [Button page](/components/button) shows
+its live demo and generated props table.
+
+## Compose the first Block
+
+A Block is a pre-composed section that takes its content as props. It ships no
+copy of its own, so the heading, the actions and the numbers all come from you.
+
+```tsx
+import { Cta01 } from '@nanisoft/prism-ui/blocks/cta-01'
+
+export function Closing() {
+  return (
+    <Cta01
+      title="Start with one block"
+      description="Keep the tokens and reshape the rest."
+      action={{ label: 'Read the guides', href: '/guides' }}
+    />
+  )
+}
+```
+
+The block's own page lists the props it accepts and renders the same component
+live. A Page composes blocks and components into a whole screen; see
+[Composition](/overview/composition) for when to reach for each layer.
+
+## What is next
+
+- [Architecture](/overview/architecture) explains the package boundary and the
+  catalogue.
+- [Theming](/overview/theming) covers packs, modes and flash-free switching.
+- [Using LLMs](/overview/using-llms) wires an agent to the same source.

package/dist/md/overview/theming.md

@@ -0,0 +1,89 @@
+# Theming
+
+Packs and modes are two independent axes, delivered as markup attributes with no override path.
+
+Prism themes are complete atmospheres, not a primary-colour swap. A pack changes
+the page ground, the surfaces, the hairlines, the text bases and the focus
+treatment together.
+
+## Two axes
+
+Theming is two independent axes:
+
+- **Pack** selects the palette: `default`, `blush`, `mint`, `lavender`, `sky`
+  or `peach`.
+- **Mode** selects the appearance: `light` or `dark`.
+
+A **theme** is one pack in one mode, such as Blush dark. It is a fully resolved
+token set, not an object and not an API. There is no theme factory.
+
+| Pack | Character |
+| --- | --- |
+| `default` | The neutral base. `primary` reads as ink, not colour. |
+| `blush` | Soft rose, with the softest radius of the set. |
+| `mint` | Soft green, calm and low-energy. |
+| `lavender` | Soft violet, the most saturated brand ramp. |
+| `sky` | Soft blue, the crispest hue and the smallest radius. |
+| `peach` | Soft orange, the warmest hue and the roundest corners. |
+
+## Declarative selection
+
+Put `data-pack` on any element to make it, and its subtree, a theme boundary.
+Add the `dark` class for dark mode. The neutral base pack is the absence of
+`data-pack`, so it is expressed by omitting the attribute.
+
+```tsx
+<!-- the default pack, light -->
+<html lang="en">
+
+<!-- Lavender, dark -->
+<html lang="en" data-pack="lavender" class="dark">
+```
+
+This form is server-rendered and needs no JavaScript. It is also the cheapest
+way to show several packs at once: any subtree can carry its own `data-pack`.
+See the [themes page](/foundation/themes) for all packs side by side.
+
+## Programmatic selection
+
+When a user needs to switch and persist a choice, mount the optional provider
+and read the hook.
+
+```tsx
+import { PrismProvider, usePrismTheme } from '@nanisoft/prism-ui/provider'
+
+function PackPicker() {
+  const { pack, setPack, mode, toggleMode } = usePrismTheme()
+  return (
+    <button onClick={() => setPack('peach')}>
+      {pack} / {mode}
+    </button>
+  )
+}
+
+export function App({ children }: { children: React.ReactNode }) {
+  return <PrismProvider>{children}</PrismProvider>
+}
+```
+
+The provider's only outputs are the two document-element attributes and the
+context. It has no override parameter, no token object and no merge.
+
+## Flash-free first paint
+
+Under a static export there is no server and no middleware, so a blocking inline
+script in `<head>` is what honours a stored choice before first paint. The
+provider's package includes `PrismThemeScript` for exactly this, and the root
+element carries `suppressHydrationWarning` because the script may set the
+attributes before React hydrates.
+
+## There is no consumer theming
+
+Prism does not expose `createPrismTheme`, a per-key merge or semantic overrides.
+The supported path is to select a pack and a mode. A product that needs a
+different palette, a new semantic token or a changed component should request it
+upstream, so every consumer benefits from the change and no project carries a
+private fork.
+
+`className` is for layout composition only. Changing a Prism-owned visual
+property through a class is not supported.

package/dist/md/overview/using-llms.md

@@ -0,0 +1,83 @@
+# Using LLMs
+
+Using LLMs against Prism: the corpus, the Markdown mirror and the read-only MCP endpoint, so an agent reads the same source the human documentation does.
+
+Prism treats agents as first-class consumers. The site, the package declarations,
+the demo sources, the Markdown mirror and the MCP endpoint all project the same
+source, so an agent and a human cannot be told different things.
+
+## Fast path
+
+1. Read `llms.txt` for the catalogue and the page index.
+2. Use `search_docs` when the item name is unknown.
+3. Use `get_item_doc` for the assembled item documentation and its rules.
+4. Use `get_item_props` for the public TypeScript surface.
+5. Use `get_item_source` for the verbatim demo and the public import line.
+6. Use `get_theme_doc` before choosing a pack or reading a token scale.
+7. Use `get_changelog` before upgrading a dependency on Prism.
+
+## The MCP endpoint
+
+The endpoint is public and read-only. It returns Markdown and never writes to a
+consumer project.
+
+```json
+{
+  "mcpServers": {
+    "prism": {
+      "type": "http",
+      "url": "https://prism.nanisoft.com/mcp"
+    }
+  }
+}
+```
+
+## The nine tools
+
+| Tool | Use |
+| --- | --- |
+| `list_items` | Browse the catalogue, filtered by `kind` and `category` |
+| `get_item_doc` | Read the assembled item documentation |
+| `get_item_props` | Read the `## Props` subset of an item |
+| `get_item_source` | Copy the verbatim demo plus the import line |
+| `get_theme_doc` | Read the token contract and the bound scales |
+| `list_pages` | Browse the non-item pages: Overview, Foundation, Content, Changelogs |
+| `get_page` | Read one non-item page as Markdown |
+| `search_docs` | Search the complete corpus and return references |
+| `get_changelog` | Read a published package's changelog, optionally one version |
+
+`list_items` is the one tool that exists because a kind exists; the other seven
+exist because a retrieval pattern exists, and `get_changelog` exists because a
+published breaking change has to be findable by an agent. Search returns
+references, not page bodies, so an agent follows a hit with `get_item_doc` or
+`get_page`.
+
+`get_changelog` takes a package and an optional version, and returns that
+package's own `CHANGELOG.md` as it shipped rather than a summary of it. The
+Changelogs section of this site renders the same bytes, so an agent and a reader
+cannot be told different things about what changed.
+
+## Import contract for generated code
+
+Generated applications import from `@nanisoft/prism-ui`. The internal Base UI
+dependency is not a consumer dependency and must not appear in application
+source.
+
+```tsx
+import { Button } from '@nanisoft/prism-ui/components/button'
+import { Hero01 } from '@nanisoft/prism-ui/blocks/hero-01'
+```
+
+The internal shadcn registry never appears in generated code. It is an integrity
+artifact inside the package, not an install lane.
+
+## Truth rules
+
+- The corpus is versioned with `prism-ui`. Compare the version echoed by
+  `list_items` with the installed package when behaviour looks inconsistent.
+- Demos are single-source files: the same text is rendered live, copied by the
+  site, and returned by `get_item_source`.
+- A generated item has exactly one demo. When an item has no demo, the tool says
+  so rather than fabricating one.
+- Product claims belong to the product team. The corpus documents implementation
+  and usage, never invented customer evidence.

package/dist/md/pages/auth-page.md

@@ -0,0 +1,149 @@
+# AuthPage
+
+A full authentication screen composing a sign-in form with an optional supporting card.
+
+```tsx
+import { AuthPage } from '@nanisoft/prism-ui/pages/auth-page'
+```
+
+## Overview
+
+AuthPage is a complete authentication screen. It composes a sign-in form with an
+optional supporting card, and it owns the centering, the breakpoint and the
+fallback column only. The form carries the credentials, the error slot and the
+submit; the card carries product context beside it.
+
+The page composes these parts:
+
+| Region | Piece | Role |
+| --- | --- | --- |
+| Form | AuthForm01 | the title, the credential fields, the remember row and the submit |
+| Support | Card | an optional surface beside the form for context or reassurance |
+| Footer | footer | a line under the form, such as a legal note or a link |
+
+Every field, label, handler, error and supporting string is a prop. The page
+fetches nothing and imports no router, so the consumer owns the request and the
+links. When no `aside` is passed the layout is one centered column; with one it
+is a two-column split from the large breakpoint up, and the card falls below the
+form on a narrow screen.
+
+## Guidelines
+
+### When to use
+
+Use AuthPage for a sign-in screen whose only task is to collect one email and one
+secret. It works when the screen is the first thing a returning reader sees and
+the supporting card answers a question they are likely to have at that moment.
+
+### When not to use
+
+Do not use it for registration, password reset or profile editing. Those have
+different field sets, and a sign-in card with the wrong fields is a dead end;
+compose a form from the same parts instead.
+
+Do not use it when the screen must carry more than a few words of supporting
+content. The card is context beside a form, not a second page; a longer story
+belongs on a marketing route the reader saw before signing in.
+
+### Best practices
+
+- Set `type`, `autoComplete` and `required` on every field. Browsers use them to
+  fill and validate, so the typing is the whole reason the field is typed.
+- Keep the error to one sentence and mark the failed fields. AuthForm01 sets
+  `aria-invalid` when an error is present, so the form and the message agree.
+- Disable the submit control while a request is in flight and pass `pendingLabel`,
+  so the reader sees that work is happening.
+- Omit `aside` when there is nothing true to say. An empty card is worse than a
+  single centered form.
+- Keep the footer to one line, such as a legal note or a route to create an
+  account, and pass the link in as a node so the consumer owns it.
+
+### Content guidelines
+
+- The title is a short verb phrase in sentence case: "Sign in", "Continue".
+- The description states the outcome, not a policy.
+- An error says what to do next: "Enter your email and password to continue."
+
+**The auth page, with a controlled form and a supporting card.**
+
+```tsx
+'use client'
+
+import { useState } from 'react'
+
+import { AuthPage } from '@nanisoft/prism-ui/pages/auth-page'
+
+/** The auth page, with a controlled form and a supporting card. */
+export default function AuthPageDemo() {
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [error, setError] = useState<string>()
+
+  return (
+    <AuthPage
+      form={{
+        title: 'Sign in',
+        description: 'Welcome back. Enter your details to continue.',
+        error,
+        submitLabel: 'Sign in',
+        fields: [
+          {
+            id: 'auth-page-email',
+            label: 'Email',
+            type: 'email',
+            autoComplete: 'email',
+            placeholder: 'you@example.com',
+            value: email,
+            onChange: setEmail,
+            required: true,
+          },
+          {
+            id: 'auth-page-password',
+            label: 'Password',
+            type: 'password',
+            autoComplete: 'current-password',
+            value: password,
+            onChange: setPassword,
+            required: true,
+          },
+        ],
+        remember: { id: 'auth-page-remember', label: 'Remember me for 30 days' },
+        onSubmit: (event) => {
+          event.preventDefault()
+          setError(
+            email && password ? undefined : 'Enter your email and password to continue.',
+          )
+        },
+      }}
+      aside={{
+        title: 'Everything in one workspace',
+        description: 'Projects, deployments and usage, without a second tool.',
+        children: (
+          <ul className="text-muted-foreground flex flex-col gap-2 text-sm">
+            <li>One place for every team</li>
+            <li>Usage that updates as you deploy</li>
+            <li>Roles from viewer to admin</li>
+          </ul>
+        ),
+      }}
+      footer={<p>No account yet? Create one.</p>}
+    />
+  )
+}
+```
+
+## Props
+
+**`form`** `ComponentProps<typeof AuthForm01>` · required · default: — — The credential form.
+**`aside`** `AuthPageAside` · optional · default: — — A supporting card beside the form. Omit it for a single centered column.
+**`footer`** `ReactNode` · optional · default: — — A node under the form, such as a legal line or a link to another screen.
+
+## Composition
+
+**`exports`** `AuthPage` — the public runtime names this Page promises
+**`source`** `packages/ui/src/pages/auth-page/index.tsx` — the file this Page is defined in
+**`dependencies`** `AuthForm01, Card` — the public Prism exports this item composes
+
+## Blocks
+
+- [AuthForm01](https://prism.nanisoft.com/blocks/auth-form-01.md)