@nanisoft/prism-llms 0.4.0 → 0.5.1

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

@@ -0,0 +1,199 @@
+# MarketingPage
+
+A complete marketing page composing a hero, a feature grid, a KPI row, a plan comparison and a closing call to action.
+
+```tsx
+import { MarketingPage } from '@nanisoft/prism-ui/pages/marketing-page'
+```
+
+## Overview
+
+MarketingPage is a complete marketing screen. It composes five blocks in reading
+order and passes each one its own content, so the page adds the sequence and
+nothing else: an opening hero, a capability grid, a row of key figures, a plan
+comparison and a closing call to action.
+
+The page composes these blocks:
+
+| Section | Block | Role |
+| --- | --- | --- |
+| Opening | Hero01 | the headline, the supporting line and one or two actions |
+| Capabilities | FeatureGrid01 | a grid of short feature blurbs, with or without icons |
+| Figures | Stats01 | two to four key numbers, each with an optional delta |
+| Plans | Pricing01 | a plan comparison with one highlighted tier |
+| Closing | Cta01 | the final call to action on a filled surface |
+
+Every string, number, icon, price and action is a prop. The page ships no sample
+copy and fetches nothing. It is a product-agnostic screen model, so a consumer
+installs it, passes their own content and owns the links. It is not this site's
+own landing route: that page is site-owned and composes the same blocks at the
+call site.
+
+## Guidelines
+
+### When to use
+
+Use MarketingPage for a public landing route whose job is to introduce a product
+and move a reader to one next step. It works when the five sections form one
+argument from the headline to the closing action.
+
+### When not to use
+
+Do not use it inside an authenticated screen. A hero and a plan comparison carry
+marketing weight that competes with the task an application screen exists to
+support; compose the blocks you need directly instead.
+
+Do not use it as a documentation page. Guides and item pages have their own
+shell, and a marketing hero would sit above content that is already scoped.
+
+Do not use it when the sequence is not the five sections. The page is a fixed
+composition; a different order or a missing section is a page the consumer
+builds from the blocks.
+
+### Best practices
+
+- Pass every block its own props. The page does not merge or default them, so
+  omitting a section's content renders an empty section rather than a fallback.
+- Keep the hero as the only `h1`. The page defaults `headingLevel` to `h1`; when
+  it is embedded under a heading the consumer already owns, pass one level
+  deeper and the rest of the outline follows.
+- Put the primary action on the hero and the secondary action on the closing
+  band, not both in each. One decision per band keeps the page from reading as
+  two pitches.
+- Keep the figures real. Stats01 renders exactly the numbers it is given, so the
+  page makes no claim the consumer did not make.
+
+### Content guidelines
+
+- The hero headline states an outcome, not a feature name.
+- The feature titles are the four or five things the product does; the bodies
+  are one sentence each.
+- The closing line is a verb phrase and the action names what the reader gets.
+
+**The marketing page, composed with placeholder sections.**
+
+```tsx
+import { Blocks, Palette, ShieldCheck, Zap } from 'lucide-react'
+
+import { MarketingPage } from '@nanisoft/prism-ui/pages/marketing-page'
+
+/**
+ * The marketing page, composed with placeholder sections.
+ *
+ * The page owns the sequence; the demo owns the strings, the numbers and the
+ * feature icons. It renders at `h3` because the documentation page already owns
+ * an `h1`, which is the same reason a block demo nests its heading.
+ */
+export default function MarketingPageDemo() {
+  return (
+    <MarketingPage
+      headingLevel="h3"
+      hero={{
+        eyebrow: 'Preview',
+        title: 'A headline that fits on two lines',
+        description:
+          'One or two sentences of supporting copy, so the measure and the spacing around it can be judged.',
+        actions: [
+          { label: 'Primary action' },
+          { label: 'Secondary', variant: 'outline' },
+        ],
+      }}
+      features={{
+        eyebrow: 'Preview',
+        title: 'Section heading',
+        description: 'An optional line that explains what the set below it has in common.',
+        features: [
+          {
+            icon: Palette,
+            title: 'First item',
+            body: 'A short sentence describing the first thing in the set.',
+          },
+          {
+            icon: Blocks,
+            title: 'Second item',
+            body: 'A short sentence describing the second thing in the set.',
+          },
+          {
+            icon: Zap,
+            title: 'Third item',
+            body: 'A short sentence describing the third thing in the set.',
+          },
+          {
+            icon: ShieldCheck,
+            title: 'Fourth item',
+            body: 'A short sentence describing the fourth thing in the set.',
+          },
+        ],
+      }}
+      stats={{
+        eyebrow: 'Preview',
+        title: 'Section heading',
+        stats: [
+          { label: 'First metric', value: '1,284', delta: 12, hint: 'vs last month' },
+          { label: 'Second metric', value: '47.2%', delta: -3, hint: 'vs last month' },
+          { label: 'Third metric', value: '2.4d', delta: 0, hint: 'vs last quarter' },
+          { label: 'Fourth metric', value: '138' },
+        ],
+      }}
+      pricing={{
+        title: 'Section heading',
+        plans: [
+          {
+            name: 'First plan',
+            price: '$0',
+            period: ' / month',
+            body: 'One line on who it is for.',
+            features: ['First included line', 'Second included line', 'Third included line'],
+            cta: 'Choose',
+          },
+          {
+            name: 'Second plan',
+            price: '$24',
+            period: ' / month',
+            body: 'One line on who it is for.',
+            features: ['Everything in the first plan', 'One extra line', 'Another extra line'],
+            cta: 'Choose',
+            featured: true,
+          },
+          {
+            name: 'Third plan',
+            price: '$68',
+            period: ' / month',
+            body: 'One line on who it is for.',
+            features: ['Everything in the second plan', 'One extra line', 'Another extra line'],
+            cta: 'Choose',
+          },
+        ],
+      }}
+      cta={{
+        title: 'A closing line, two lines at most',
+        description: 'A sentence that says what happens next, then one action.',
+        action: { label: 'Do the thing', href: '/components/button' },
+      }}
+    />
+  )
+}
+```
+
+## Props
+
+**`hero`** `ComponentProps<typeof Hero01>` · required · default: — — The opening band: an optional eyebrow, the headline and one or two actions.
+**`features`** `ComponentProps<typeof FeatureGrid01>` · required · default: — — The capability grid below the hero.
+**`stats`** `ComponentProps<typeof Stats01>` · required · default: — — The key-figure row.
+**`pricing`** `ComponentProps<typeof Pricing01>` · required · default: — — The plan comparison.
+**`cta`** `ComponentProps<typeof Cta01>` · required · default: — — The closing call to action.
+**`headingLevel`** `HeadingLevel` · optional · default: — — The heading level for the hero. Defaults to `h1`, because a page owns the top of the document outline. A consumer that embeds the page under a heading it already owns passes one level deeper.
+
+## Composition
+
+**`exports`** `MarketingPage` — the public runtime names this Page promises
+**`source`** `packages/ui/src/pages/marketing-page/index.tsx` — the file this Page is defined in
+**`dependencies`** `Cta01, FeatureGrid01, Hero01, Pricing01, Stats01` — the public Prism exports this item composes
+
+## Blocks
+
+- [Cta01](https://prism.nanisoft.com/blocks/cta-01.md)
+- [FeatureGrid01](https://prism.nanisoft.com/blocks/feature-grid-01.md)
+- [Hero01](https://prism.nanisoft.com/blocks/hero-01.md)
+- [Pricing01](https://prism.nanisoft.com/blocks/pricing-01.md)
+- [Stats01](https://prism.nanisoft.com/blocks/stats-01.md)

package/dist/md/pages/not-found-page.md

@@ -0,0 +1,105 @@
+# NotFoundPage
+
+A complete not-found screen: the status code as the heading of the page, one sentence about what happened, and the ways out.
+
+```tsx
+import { NotFoundPage } from '@nanisoft/prism-ui/pages/not-found-page'
+```
+
+## Overview
+
+NotFoundPage is a complete not-found screen: the code, what happened, and the ways
+out.
+
+All four NaniSoft sites compose one, each in its own not-found route, and three of
+them are the same six lines with a different product name on it: a display title
+carrying the code, one muted sentence, and two or three links. The fourth wrote
+the same thing in its own markup. Four hand-written screens for one shape.
+
+It is a Page rather than a Block because it is a whole screen: it owns the
+document's `h1`, it is what a router renders when a route does not resolve, and
+the band's job is not separable from the screen's. There is one correct page here
+and it is short.
+
+## Guidelines
+
+### When to use
+
+Use NotFoundPage as the body of whatever route your framework names for a
+not-found response: Next's `not-found.tsx`, a Nuxt error page, a route your own
+router falls through to.
+
+Use it for every status that means "this address is not a page here", not only
+404. A 410 and a 404 are the same screen with a different code, and the code is a
+prop.
+
+### When not to use
+
+Do not use it for a request that failed. That is an error page with a retry, and a
+reader who sees "this page does not exist" when the page exists and did not load
+will not believe you next time.
+
+Do not use it for a permission failure the reader might be granted later. That is
+a 403, and it needs a sign-in link rather than a way back to the landing.
+
+### Best practices
+
+- **The code is the `h1` and the sentence is not.** A not-found page whose `h1` is
+  "Page not found" gives a search engine and a screen reader nothing distinct to
+  index, and the code is the one string on the page that is the same for every
+  broken URL. The code takes the display step and the sentence takes the muted one,
+  which is the reverse of what a reader sees first and the right way round for
+  anything that reads the outline.
+- Put the most useful destination first, and weight it as the primary action. A
+  not-found page that offers the homepage link before the documentation sends a
+  reader further from what they wanted.
+- Leave `newTab` off every link. A reader who followed a broken link and is sent
+  to a new tab has to find their way back.
+- Use the `children` slot for a search box or a list of recent posts, which is
+  what turns a dead end into a page.
+
+### Content guidelines
+
+- Write the sentence as a fact about the address, not as an apology. "No node
+  here" beats "Sorry, we could not find that page".
+- Say whether the page might exist later if it does. "This page does not exist
+  (yet)" is one clause longer and saves a support ticket.
+- Keep each link label to one or two words.
+
+**The not-found screen: the code as the h1, one sentence, and the ways out.**
+
+```tsx
+import { NotFoundPage } from '@nanisoft/prism-ui/pages/not-found-page'
+
+/** The not-found screen: the code as the h1, one sentence, and the ways out. */
+export default function NotFoundPageDemo() {
+  return (
+    <NotFoundPage
+      code="404"
+      title="No node here."
+      description="The estate is fully mapped. This URL is not in the graph."
+      linksLabel="Ways out"
+      links={[
+        { label: 'Read the docs', href: '#docs' },
+        { label: 'Back to the landing', href: '#landing' },
+      ]}
+    />
+  )
+}
+```
+
+## Props
+
+**`code`** `string` · required · default: — — The status code, shown as the page's own `h1`. Required, and a string rather than a number because it is displayed, not computed: a Page never decides what code it is answering.
+**`title`** `string` · required · default: — — The headline under the code: the sentence that says what happened. It is the part a reader actually reads, and it is the caller's because every product says it differently - "No node here", "This page does not exist (yet)".
+**`description`** `string` · optional · default: — — One or two sentences under the headline, for anything a reader should know before they follow one of the links: that the URL may be mistyped, that the page is planned, that a search would find it.
+**`links`** `readonly NotFoundLink[]` · required · default: — — The ways out, in the order a reader should see them. Put the destination most likely to help first; a not-found page that offers a homepage link before the documentation sends a reader further from what they wanted.
+**`linksLabel`** `string` · required · default: — — The accessible name of the row of ways out. It is required, because it is a word a reader hears and a Page that ships no copy ships no reader-facing copy either. "Ways out" is the Page's own phrasing; a site that files its destinations differently names the same landmark differently.
+**`children`** `ReactNode` · optional · default: — — A slot for whatever else the site wants to say here: a search box, a list of recent posts, a contact address.
+**`className`** `string` · optional · default: — — Layout only, exactly as on every Component. Changing a Prism-owned visual property from here is prohibited.
+
+## Composition
+
+**`exports`** `NotFoundPage` — the public runtime names this Page promises
+**`source`** `packages/ui/src/pages/not-found-page/index.tsx` — the file this Page is defined in
+**`dependencies`** `CtaLink, Prose, Section` — the public Prism exports this item composes

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

@@ -0,0 +1,206 @@
+# SettingsPage
+
+A full settings screen composing the app shell, a page header and tabs of grouped settings forms.
+
+```tsx
+import { SettingsPage } from '@nanisoft/prism-ui/pages/settings-page'
+```
+
+## Overview
+
+SettingsPage is a complete settings screen. It composes the shell, a page header
+and a set of tabs, where each tab is either a saved settings form or a read-only
+panel. The page owns the sequence and the tab wiring only.
+
+The page composes these parts:
+
+| Region | Piece | Role |
+| --- | --- | --- |
+| Frame | AppShell01 | the navigation rail, the top bar and the mobile navigation sheet |
+| Header | PageHeader01 | the trail, the screen title and its actions |
+| Tabs | Tabs, TabsList, TabsTrigger, TabsContent | the peer settings groups |
+| Forms | SettingsPanel01 | the grouped and saved form for one tab |
+
+A tab that carries `panel` renders `SettingsPanel01`: a titled card with grouped
+sections, a save footer and one submit. A tab that carries `content` renders the
+node as-is, which suits a read-only summary or a view that is not a form. Sections,
+fields, options and labels are all props, and the page fetches nothing.
+
+## Guidelines
+
+### When to use
+
+Use SettingsPage when a screen changes several settings that group naturally, and
+each group can be saved on its own. It works when the tabs are stable and a reader
+returns to one group rather than scanning the whole screen.
+
+### When not to use
+
+Do not use it for a single setting. One field behind a tab is a heavier frame
+than the choice deserves; put the control on the screen that owns it.
+
+Do not use it when the settings must be compared side by side. Tabs hide one
+group to show another, so a choice that depends on another group's value belongs
+on one page, not behind a tab.
+
+### Best practices
+
+- Keep one save per panel. A mixed model, where some fields save and others apply
+  immediately, makes the footer's promise unclear.
+- Give every field a stable `id`, so the label is linked to the control.
+- Use `content` for a read-only group. A panel with no `submitLabel` renders no
+  footer, which is the honest shape for a view that does not save.
+- Set `defaultValue` to the group a reader is most likely to want, rather than
+  relying on the first tab by luck.
+- Pass the same navigation node to both the rail and the sheet, and keep its ids
+  unique because AppShell01 renders it twice.
+
+### Content guidelines
+
+- A tab label is one word in sentence case: "General", "Notifications".
+- A section title is one or two words and a field label is a short noun phrase.
+- A description states the effect of the group, not a policy for it.
+
+**The settings page, with a grouped form per tab.**
+
+```tsx
+'use client'
+
+import { SettingsPage } from '@nanisoft/prism-ui/pages/settings-page'
+
+const LINKS = [
+  { href: '#general', label: 'General', current: false },
+  { href: '#settings', label: 'Settings', current: true },
+  { href: '#members', label: 'Members', current: false },
+]
+
+/** The settings page, with a grouped form per tab. */
+export default function SettingsPageDemo() {
+  return (
+    <SettingsPage
+      shell={{
+        navigationLabel: 'Primary',
+        brand: <span className="text-sm font-semibold">Northwind</span>,
+        breadcrumbs: [{ label: 'Settings', href: '#settings' }, { label: 'Workspace' }],
+        navigation: (
+          <ul className="flex flex-col gap-1 text-sm">
+            {LINKS.map((link) => (
+              <li key={link.href}>
+                <a
+                  href={link.href}
+                  className={
+                    link.current
+                      ? 'bg-accent text-accent-foreground block rounded-md px-3 py-2 font-medium'
+                      : 'text-muted-foreground hover:text-foreground block rounded-md px-3 py-2'
+                  }
+                >
+                  {link.label}
+                </a>
+              </li>
+            ))}
+          </ul>
+        ),
+      }}
+      header={{
+        title: 'Workspace settings',
+        description: 'Manage how this workspace behaves for everyone on the team.',
+      }}
+      tabs={[
+        {
+          value: 'general',
+          label: 'General',
+          panel: {
+            title: 'General',
+            description: 'Shown to everyone you collaborate with.',
+            submitLabel: 'Save changes',
+            secondaryAction: { label: 'Cancel' },
+            sections: [
+              {
+                id: 'identity',
+                title: 'Identity',
+                fields: [
+                  {
+                    kind: 'text',
+                    id: 'settings-workspace-name',
+                    label: 'Workspace name',
+                    defaultValue: 'Northwind',
+                  },
+                  {
+                    kind: 'textarea',
+                    id: 'settings-workspace-description',
+                    label: 'Description',
+                    placeholder: 'What does this workspace do?',
+                    rows: 3,
+                  },
+                  {
+                    kind: 'select',
+                    id: 'settings-workspace-region',
+                    label: 'Data region',
+                    placeholder: 'Choose a region',
+                    defaultValue: 'eu-west',
+                    options: [
+                      { label: 'Europe West', value: 'eu-west' },
+                      { label: 'US East', value: 'us-east' },
+                    ],
+                  },
+                ],
+              },
+            ],
+          },
+        },
+        {
+          value: 'notifications',
+          label: 'Notifications',
+          panel: {
+            title: 'Notifications',
+            description: 'Choose what the workspace sends and when.',
+            submitLabel: 'Save changes',
+            sections: [
+              {
+                id: 'email',
+                title: 'Email',
+                fields: [
+                  {
+                    kind: 'switch',
+                    id: 'settings-weekly-digest',
+                    label: 'Weekly digest',
+                    description: 'A summary of activity every Monday.',
+                    defaultChecked: true,
+                  },
+                  {
+                    kind: 'switch',
+                    id: 'settings-mention-alerts',
+                    label: 'Mention alerts',
+                    description: 'Notify me when someone mentions my name.',
+                  },
+                ],
+              },
+            ],
+          },
+        },
+      ]}
+    />
+  )
+}
+```
+
+## Props
+
+**`shell`** `Omit<ComponentProps<typeof AppShell01>, 'children'>` · required · default: — — The frame: rail, top bar and mobile navigation sheet.
+**`header`** `ComponentProps<typeof PageHeader01>` · required · default: — — The page title band.
+**`tabs`** `SettingsPageTab[]` · required · default: — — The tabs, in order. At least one is required.
+**`defaultValue`** `string` · optional · default: — — The tab shown first, for uncontrolled tabs. Defaults to the first tab.
+**`value`** `string` · optional · default: — — The controlled active tab.
+**`onValueChange`** `(value: string) => void` · optional · default: —
+
+## Composition
+
+**`exports`** `SettingsPage` — the public runtime names this Page promises
+**`source`** `packages/ui/src/pages/settings-page/index.tsx` — the file this Page is defined in
+**`dependencies`** `AppShell01, PageHeader01, SettingsPanel01, Tabs` — the public Prism exports this item composes
+
+## Blocks
+
+- [AppShell01](https://prism.nanisoft.com/blocks/app-shell-01.md)
+- [PageHeader01](https://prism.nanisoft.com/blocks/page-header-01.md)
+- [SettingsPanel01](https://prism.nanisoft.com/blocks/settings-panel-01.md)

package/dist/prism-skill.md

@@ -0,0 +1,50 @@
+# Prism agent skill
+
+Prism is NaniSoft's design system: design tokens, a React component library, a
+documentation site, and this agent surface. This is the fast path. The index is
+[`/llms.txt`](https://prism.nanisoft.com/llms.txt) and every page in full is
+[`/llms-full.txt`](https://prism.nanisoft.com/llms-full.txt); both are generated from the
+checked catalogue and the authored pages.
+
+## Start here
+
+```tsx
+import '@nanisoft/prism-ui/styles.css'
+
+import { PrismProvider, PrismThemeScript } from '@nanisoft/prism-ui/provider'
+```
+
+Import the one stylesheet once. The provider is optional: the declarative axes
+are `data-pack` on `<html>` and the `dark` class for mode.
+
+## Import contract
+
+- Components: `@nanisoft/prism-ui/components/<slug>`
+- Blocks: `@nanisoft/prism-ui/blocks/<slug>`
+- Pages: `@nanisoft/prism-ui/pages/<slug>`
+
+Compound parts stay inside their module. Base UI and every internal path are
+never a consumer import.
+
+## MCP
+
+The read-only MCP endpoint is `https://prism.nanisoft.com/mcp`. It exposes nine tools:
+`list_items`, `get_item_doc`, `get_item_props`, `get_item_source`,
+`get_theme_doc`, `list_pages`, `get_page`, `search_docs` and
+`get_changelog`.
+
+## Truth rules
+
+- Prism is the one source of truth. A consumer composes; it never writes CSS and
+  never overrides a style.
+- There is no override path. When Prism lacks a component, token or variant,
+  request it upstream.
+- Generated code imports from `@nanisoft/prism-ui` only.
+
+## This corpus
+
+Generated from the catalogue and the authored pages: 34
+Components, 19 Blocks and 7 Pages, plus the Overview,
+Foundation, Content and Changelogs pages. The Changelogs pages are each
+published package's own changelog, byte for byte; `get_changelog` returns one
+package's, optionally one version of it.