@nanisoft/prism-llms 0.4.0 → 0.5.1

package/dist/md/content/glossary.md

@@ -0,0 +1,69 @@
+# Glossary
+
+Definitions for the terms used across Prism. The terms come from CONTEXT.md and this page hosts them.
+
+These definitions are the design system's vocabulary. They are the same terms
+the repository's `CONTEXT.md` defines, and they are the reason the docs and the
+code use one word for one thing.
+
+## Theming
+
+- **Pack**: one of the authored palettes, the neutral base `default` and the
+  five pastels Blush, Mint, Lavender, Sky and Peach. A pack owns a generated
+  OKLCH ramp family and its own radius.
+- **Mode**: the appearance of a pack, `light` or `dark`.
+- **Theme**: one pack in one mode. A theme is a fully resolved token set, not an
+  object and not an API.
+- **Pack id**: the string that selects a pack at runtime, such as `blush`.
+  Absence of a pack id means the default pack.
+
+## Tokens
+
+- **Foundation token**: a raw ramp value that carries no meaning.
+- **Semantic token**: a named intent, authored as an alias into the foundation
+  tier. Its name is emitted verbatim as a CSS custom property.
+- **Token contract**: the set of semantic names emitted as CSS custom
+  properties, byte for byte identical to shadcn's variable contract.
+- **Token**: a value in the DTCG source, either foundation or semantic.
+
+## Composition
+
+- **Component**: a focused, accessible, product-agnostic export with one job,
+  and a catalogue item of kind `component`.
+- **Block**: a pre-composed, product-agnostic section assembled from Components.
+  A Block takes its content as props and fetches no application data.
+- **Page**: a complete structural composition of Blocks and Components that
+  models a whole screen.
+- **Item**: one entry in the catalogue, of any kind.
+- **Kind**: the closed discriminator on an item: `component`, `block` or `page`.
+- **Category**: one of the seven role groups a Component is assigned to. A Block
+  or a Page has no category.
+
+## Catalogue and source
+
+- **Catalogue**: the checked list of every Component, Block and Page, and the
+  single source for navigation, item documentation, the corpus and the agent
+  surface.
+- **Registry**: the shadcn registry inside the component package. It is an
+  internal integrity artifact, never a public install lane.
+- **Owned source**: Prism-authored code a consumer composes through documented
+  package exports.
+- **Internal dependency**: a dependency used inside a package to provide
+  behaviour or structure, such as Base UI. It is never public API.
+- **Provider**: the optional client module that carries pack and mode through
+  context and writes the two document-element attributes.
+
+## Agents
+
+- **Corpus**: the deterministic projection of the catalogue and the
+  documentation into `llms.txt`, the Markdown mirror and the store.
+- **Store**: the type-checked projection of the corpus that the MCP server reads
+  at runtime. It is generated, never hand-edited.
+- **Agent surface**: the corpus and the read-only MCP endpoint through which an
+  agent reads the same catalogue, props, examples and tokens as this site.
+
+## Words retired
+
+These words are historical and MUST NOT be revived: primitive (as a unit noun),
+colourway, variant (as a unit noun), beam-dark, pass-through, wrapper, agent
+door, internal primitive, catalog (in prose) and layer (as a unit noun).

package/dist/md/content/product-vocabulary.md

@@ -0,0 +1,53 @@
+# Product vocabulary
+
+The preferred spelling and casing of NaniSoft product terms, and the terms to avoid.
+
+Vocabulary is not standardised across sources. Use the spelling and casing on
+this page, and do not guess from another document.
+
+RULE: Always use the spelling and capitalisation shown here in every product
+string and in every piece of documentation.
+
+## Sentence case
+
+RULE: Write these terms lowercase in descriptions and body text.
+
+- pack: one of Prism's authored palettes, such as Blush or Sky.
+- mode: the appearance of a pack, `light` or `dark`.
+- token: a value in the DTCG source.
+- component, block and page: the three composition units, in prose. See the
+  [Glossary](/content/glossary) for their definitions.
+
+## Title case
+
+RULE: Write these terms in title case in every context.
+
+- Prism
+- NaniSoft
+- Blush, Mint, Lavender, Sky, Peach: the five pastel pack names, as proper nouns.
+
+## Product terms
+
+- **Prism**: NaniSoft's design system. Never "the Prism system" or "Prism UI".
+- **pack**: a palette. Never "theme" for a palette; a theme is a pack in a mode.
+- **mode**: `light` or `dark`, written in code font when naming the value.
+- **semantic token**: a named intent that aliases into the foundation tier.
+- **foundation token**: a raw ramp value that carries no meaning.
+
+## Terms to avoid
+
+RULE: Never use a term in the left column. Use the replacement in the right
+column instead.
+
+| Avoid | Use instead |
+| --- | --- |
+| colourway, color scheme, skin | pack |
+| beam-dark, appearance | dark mode, or the mode |
+| theme id | pack id |
+| primitive, base value | foundation token, or Component |
+| wrapper, pass-through | Component |
+| catalog (in prose) | catalogue |
+| admin panel, admin console | the page's real name |
+| pop up, popup, pop-up | dialog |
+| login (as a noun) | sign-in |
+| e-mail | email |

package/dist/md/content/voice.md

@@ -0,0 +1,52 @@
+# Voice
+
+NaniSoft's fixed voice qualities, and how tone shifts by context.
+
+Voice is fixed. It does not change from feature to feature or from screen to
+screen. Every piece of product copy MUST be clear, human and helpful. All three,
+always.
+
+Tone is the part that moves. The same voice sounds different in an error than in
+a success message, and the context chooses the tone.
+
+## Clear
+
+Write like a knowledgeable colleague explaining something, not a manual.
+
+- RULE: Use plain words.
+- RULE: Be as short as the meaning allows.
+- RULE: Say exactly what to do or where to go.
+
+## Human
+
+Write to a person, in the first and second person.
+
+- RULE: Use "you" for the reader and "we" for NaniSoft.
+- RULE: Use contractions where they read naturally.
+- RULE: Avoid jargon unless the glossary defines it, and define it on first use.
+
+## Helpful
+
+Every message has a job. If it has no job, delete it.
+
+- RULE: Tell the reader what happened and what to do next.
+- RULE: Never blame the reader.
+- RULE: Never leave a dead end. Every error MUST name a recovery.
+
+## Choosing the tone
+
+| Context | Reader's state | Tone | Example |
+| --- | --- | --- | --- |
+| Errors, failures, empty states | Frustrated or confused | Matter-of-fact and direct | "No projects found. Change or clear your filters." |
+| Completed setup, saved work | Pleased | Plainly positive, no celebration | "Your changes are saved." |
+| Destructive actions | Cautious | Explicit and calm | "Delete this project? This cannot be undone." |
+| First run, onboarding | Curious | Brief and encouraging | "Add your first project to see it here." |
+
+RULE: A success message MUST state what changed, not congratulate the reader.
+RULE: A destructive confirmation MUST name the thing and the consequence.
+
+## Judgment
+
+These qualities are principles. Apply them with judgment, and use
+[Writing mechanics](/content/writing-mechanics) for the concrete rules on
+capitalisation, punctuation and length.

package/dist/md/content/writing-mechanics.md

@@ -0,0 +1,58 @@
+# Writing mechanics
+
+Capitalisation, punctuation, grammar and structure rules for NaniSoft product copy.
+
+These are the mechanical rules. They are narrower than voice and tone, and they
+are the ones a reviewer can check without judgment.
+
+## Capitalisation
+
+RULE: Write sentences and UI labels in sentence case. Capitalise the first word
+and proper nouns only.
+
+RULE: Use title case only for the product's own name and for a pack name when it
+is a proper noun in a heading.
+
+RULE: Do not capitalise a generic word to make it look important. "Dashboard",
+"settings" and "project" are lowercase in a sentence.
+
+## Punctuation
+
+RULE: Use the serial comma in a list of three or more items.
+
+RULE: Use periods in complete sentences and in helper text that is a sentence.
+Omit the period in a label, a button, a heading and a short fragment.
+
+RULE: Never use an exclamation mark twice in one message, and never use one in an
+error.
+
+RULE: Use a colon to introduce a list, and a semicolon when two independent
+clauses are close enough to share a sentence.
+
+RULE: Do not use em dashes or en dashes. Use a period, a comma, a colon or a
+plain hyphen.
+
+## Grammar
+
+RULE: Write in the active voice.
+
+RULE: Address the reader as "you". Refer to NaniSoft as "we".
+
+RULE: Use the present tense for what the product does, and the past tense only
+for something that already happened.
+
+RULE: Keep one idea per sentence, and keep a sentence under 25 words where the
+meaning allows.
+
+## Syntax and structure
+
+RULE: Lead each screen or dialog with the outcome, then the action.
+
+RULE: Put the most important information first, and the next step last.
+
+RULE: Use a numbered list when order matters, and a bulleted list when it does
+not.
+
+RULE: Prefer plain language. Replace a jargon word with a common one unless the
+jargon word is a defined product term in the
+[Product vocabulary](/content/product-vocabulary).

package/dist/md/foundation/colors.md

@@ -0,0 +1,10 @@
+# Colors
+
+The semantic colour contract and the foundation ramps behind it.
+
+Prism ships two colour families: a set of semantic roles whose names are the
+shadcn variable contract, and the foundation ramps those roles alias into. A
+component consumes a semantic utility, never a ramp step, which is what makes
+theming automatic at runtime.
+
+<ColorTokens />

package/dist/md/foundation/iconography.md

@@ -0,0 +1,14 @@
+# Iconography
+
+Prism uses Lucide for interface icons, sized on the spacing scale.
+
+Prism does not ship an icon font or a bespoke icon set. Interface icons come from
+Lucide, which the component package already depends on, and a component that
+needs an icon imports it from `lucide-react`.
+
+Icons are sized with `size-4` (1rem) in a control and `size-5` (1.25rem) in a
+tile. Both resolve through the authored spacing scale, so an icon stays in step
+with the control it sits in. Decorative icons carry `aria-hidden`, and an
+icon-only control carries an accessible name.
+
+<IconographyGrid />

package/dist/md/foundation/motion.md

@@ -0,0 +1,10 @@
+# Motion
+
+State feedback only, by token, with no entrance or scroll animation.
+
+Motion is state feedback. It is never decorative, there are no keyframes, and a
+component names a duration token and an easing token rather than a value.
+Spatial movement is guarded with `motion-safe:` so a reduced-motion preference
+removes it.
+
+<TokenTable group="motion" />

package/dist/md/foundation/radii.md

@@ -0,0 +1,9 @@
+# Radii
+
+One base radius drives the whole scale, derived as calc() multipliers.
+
+A single `--radius` token is the source, and the scale is derived from it. Each
+pack overrides the base, so changing a pack changes every rounded corner
+together.
+
+<TokenTable group="radius" />

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.