@nanisoft/prism-llms 0.3.0 → 0.5.0

package/dist/md/components/textarea.md

@@ -0,0 +1,101 @@
+# Textarea
+
+The multi-line text control for a form.
+
+```tsx
+import { Textarea } from '@nanisoft/prism-ui/components/textarea'
+```
+
+## Overview
+
+A Textarea is the multi-line text control. It renders a native `<textarea>` with
+a minimum height and a resize grip, so a reader can see more than one line of
+what they have written.
+
+It shares the Input's focus treatment: a full-strength ring on focus and a
+destructive border and ring when the control is marked with `aria-invalid`. The
+height follows the content where the browser supports field sizing, and `rows`
+remains the fallback.
+
+## Guidelines
+
+### When to use
+
+Use a Textarea for free-form text that runs past a line: a note, a comment, a
+bio, a support message, a release description.
+
+Pair it with a Field label and a helper line, and set `rows` to a height that
+shows the expected answer rather than one line.
+
+### When not to use
+
+Do not use a Textarea for a single-line value. A name or a search term does not
+need a resize grip.
+
+Do not use one for structured data the product can model as separate fields. If
+the parts have names, they deserve their own controls and validation.
+
+Do not use a Textarea for rich text. Formatting, links and embeds need an
+editor the design system does not ship.
+
+### Best practices
+
+- Set a minimum height that matches the expected answer. A box that shows one
+  line suggests the answer is one line.
+- Keep the label above the control and the helper line below it, exactly as an
+  Input does, so a form reads as one pattern.
+- Leave the resize grip available. Readers with motor or vision differences
+  often size the box to the draft they are writing.
+- Show the current and maximum length next to the field when there is a limit,
+  and count down rather than up so the remaining space is obvious.
+- Mark a failed field with `aria-invalid` and put the reason in a FieldError.
+  The border is not the message.
+
+### Content guidelines
+
+- A helper line may state the limit or the format: "Up to 500 characters",
+  "Plain text only".
+- A placeholder may sketch the expected answer, and should be shorter than the
+  label it sits under.
+- Do not repeat the label inside the placeholder. The two are read together by
+  a screen reader.
+
+**A textarea with a label and helper line, plus a disabled one.**
+
+```tsx
+import {
+  Field,
+  FieldDescription,
+  FieldLabel,
+} from '@nanisoft/prism-ui/components/field'
+import { Textarea } from '@nanisoft/prism-ui/components/textarea'
+
+/** A textarea with a label and helper line, plus a disabled one. */
+export default function TextareaDemo() {
+  return (
+    <div className="flex max-w-measure-narrow flex-col gap-4">
+      <Field>
+        <FieldLabel htmlFor="textarea-note">Release note</FieldLabel>
+        <Textarea
+          id="textarea-note"
+          rows={4}
+          placeholder="What changed, and who it affects."
+        />
+        <FieldDescription>Plain text. Markdown is added later.</FieldDescription>
+      </Field>
+      <Field>
+        <FieldLabel htmlFor="textarea-summary">Generated summary</FieldLabel>
+        <Textarea
+          id="textarea-summary"
+          defaultValue="Written by the pipeline."
+          disabled
+        />
+      </Field>
+    </div>
+  )
+}
+```
+
+## Props
+
+> Extends: the native `<textarea>` element. No additional Prism-specific props.

package/dist/md/components/tooltip.md

@@ -1,14 +1,102 @@
 # Tooltip
 
-antd Tooltip, unchanged — a pass-through re-export. Import from '@nanisoft/prism-ui'.
+The short label shown on hover or focus beside a control.
 
-```ts
-import { Tooltip } from '@nanisoft/prism-ui/components';
+```tsx
+import { Tooltip, TooltipTrigger, TooltipContent } from '@nanisoft/prism-ui/components/tooltip'
 ```
 
-`Tooltip` is antd's [Tooltip](https://ant.design/components/tooltip), re-exported unchanged.
+## Overview
 
-- Extends: antd **Tooltip** — for inherited props and demos, use the antd MCP (`antd_info Tooltip`).
-- Always import from '@nanisoft/prism-ui', never from `antd` directly.
+A Tooltip is a short label that appears on hover or focus beside the control it
+explains. It ships as `Tooltip`, `TooltipTrigger` and `TooltipContent`, all from
+the same module. The trigger stays focusable, and the tooltip opens on keyboard
+focus as well as on hover, so it is not a mouse-only affordance.
 
-_No additional props beyond the antd base component._
+The content is positioned by the library and flips when there is no room on the
+chosen side. Escape dismisses it. Because it is unavailable on touch, a tooltip
+never carries the only copy of information a reader needs.
+
+## Guidelines
+
+### When to use
+
+Use a Tooltip to name or briefly explain a control that is already visible: an
+icon-only button, an abbreviated label, or a term a reader may not know.
+
+### When not to use
+
+Do not put essential content in a Tooltip. Keyboard and pointer users can reach
+it, but touch users cannot, so anything required belongs in visible text.
+
+Do not use a Tooltip for a form field's validation message. Errors need to be
+persistent and programmatically tied to the field; a tooltip disappears.
+
+Do not use one for rich content such as a form or a menu. That is a Popover.
+
+### Best practices
+
+- Keep the content to a short phrase. A sentence is the ceiling; a paragraph
+  belongs in a Popover or on the page.
+- Attach the Tooltip to a focusable trigger. A tooltip on a plain span is
+  unreachable by keyboard.
+- Give an icon-only trigger an `aria-label` as well. The tooltip is visual help;
+  the accessible name must stand on its own.
+- Choose a side that does not cover the content the reader is looking at, and
+  let the library flip it near an edge.
+- Do not nest interactive content in a Tooltip. It opens on focus and closes on
+  blur, so anything inside it is hard to reach.
+
+### Content guidelines
+
+- Write a noun phrase or one short sentence that adds information, not a repeat
+  of the trigger's label.
+- Use sentence case and no closing period on a fragment; use one on a full
+  sentence.
+- Never make the tooltip the first place a key term appears. Explain the term
+  where it is introduced, and let the tooltip remind.
+
+**Tooltips on a text trigger and on an icon-only control.**
+
+```tsx
+'use client'
+
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@nanisoft/prism-ui/components/tooltip'
+
+/** Tooltips on a text trigger and on an icon-only control. */
+export default function TooltipDemo() {
+  return (
+    <div className="flex flex-wrap items-center gap-8 text-sm">
+      <Tooltip>
+        <TooltipTrigger className="underline decoration-dotted underline-offset-4">
+          Beta feature
+        </TooltipTrigger>
+        <TooltipContent>Not covered by the uptime target.</TooltipContent>
+      </Tooltip>
+      <Tooltip>
+        <TooltipTrigger aria-label="Copy link" className="font-medium">
+          Copy link
+        </TooltipTrigger>
+        <TooltipContent side="bottom">Copies the current page URL.</TooltipContent>
+      </Tooltip>
+    </div>
+  )
+}
+```
+
+## Props
+
+**`open`** `boolean` · optional · default: — — The controlled open state.
+**`defaultOpen`** `boolean` · optional · default: — — The initially open state, for an uncontrolled tooltip.
+**`onOpenChange`** `(open: boolean) => void` · optional · default: — — Called when the open state changes.
+**`disabled`** `boolean` · optional · default: — — Whether the tooltip is disabled.
+**`children`** `React.ReactNode` · optional · default: — — The trigger and content.
+**`delay`** `number` · optional · default: `600` — How long to wait before opening on hover, in milliseconds.
+**`closeDelay`** `number` · optional · default: `0` — How long to wait before closing, in milliseconds.
+**`side`** `'top' | 'right' | 'bottom' | 'left'` · optional · default: `top` — Which side of the trigger the tooltip is placed on.
+**`align`** `'start' | 'center' | 'end'` · optional · default: `center` — How the tooltip aligns against the trigger.
+**`sideOffset`** `number` · optional · default: `4` — The distance in pixels between the trigger and the tooltip.

package/dist/md/components/typography.md

@@ -1,14 +1,89 @@
 # Typography
 
-antd Typography, unchanged — a pass-through re-export. Import from '@nanisoft/prism-ui'.
+The text and heading components that apply the type scale.
 
-```ts
-import { Typography } from '@nanisoft/prism-ui/components';
+```tsx
+import { Text, Heading } from '@nanisoft/prism-ui/components/typography'
 ```
 
-`Typography` is antd's [Typography](https://ant.design/components/typography), re-exported unchanged.
+## Overview
 
-- Extends: antd **Typography** — for inherited props and demos, use the antd MCP (`antd_info Typography`).
-- Always import from '@nanisoft/prism-ui', never from `antd` directly.
+Typography is the pair of text exports that apply the type scale. `Heading`
+renders a document heading and `Text` renders a run of body copy, both from the
+same module.
 
-_No additional props beyond the antd base component._
+`Heading` separates the element from the visual step. The `as` prop chooses the
+outline, and `size` chooses the scale, so a section that needs an `h2` attuned
+to a compact card keeps the outline while taking a smaller visual size. `Text`
+offers `size` and a `tone`, where `tone="muted"` is the supporting copy that
+sits beside a heading.
+
+## Guidelines
+
+### When to use
+
+Use `Heading` and `Text` for long-form content and documentation, where the
+outline and the scale are the structure the reader navigates by.
+
+Use the `as` and `size` split when a heading's place in the outline and its
+visual weight are not the same decision.
+
+### When not to use
+
+Do not use Typography for a control label or a card title. Components such as
+Button and CardTitle own their own text treatment, and restyling them from the
+outside is the override the system forbids.
+
+Do not use `Heading` to make text bigger. A paragraph that is important is still
+a paragraph; emphasis comes from placement and copy.
+
+Do not use Typography to fix spacing. Rhythm comes from the container, not from
+a text size chosen to close a gap.
+
+### Best practices
+
+- Choose `as` by the document outline and `size` by the layout. One page has one
+  `h1`, and the levels below it never skip a step.
+- Let `Heading` default to `h2`. A block or an article body is composed under a
+  page heading, so the surrounding document already owns the top level.
+- Keep a prose measure near the container token. A line that runs the full
+  window is hard to track back to its start.
+- Use `tone="muted"` for supporting copy and keep it to a sentence or two. If
+  the muted text carries the point, promote it.
+- Keep headings in sentence case and leave the full stop off. A heading is a
+  label, not a sentence.
+- Do not scale text with `className`. Size is a token decision, and a one-off
+  value breaks the scale for the next reader.
+
+**The scale: a display heading, a subheading and both text tones.**
+
+```tsx
+import {
+  Heading,
+  Text,
+} from '@nanisoft/prism-ui/components/typography'
+
+/** The scale: a display heading, a subheading and both text tones. */
+export default function TypographyDemo() {
+  return (
+    <div className="flex max-w-measure flex-col gap-3">
+      <Heading as="h3" size="3xl">
+        Release notes
+      </Heading>
+      <Text tone="muted">What shipped in the last two weeks, in reading order.</Text>
+      <Heading as="h4" size="xl">
+        Fixes
+      </Heading>
+      <Text>Three defects in the table toolbar and one in the theme switcher.</Text>
+      <Text as="span" size="sm" tone="muted">
+        Updated 12 August.
+      </Text>
+    </div>
+  )
+}
+```
+
+## Props
+
+**`size`** `"sm" | "lg" | "base" | null | undefined` · optional · default: —
+**`tone`** `"default" | "muted" | null | undefined` · optional · default: —

package/dist/md/content/about-content.md

@@ -0,0 +1,36 @@
+# About content
+
+What "content" means at NaniSoft, and the scope of this section.
+
+Content is the information in a user interface that works alongside the visual
+design. It includes every string a person reads inside a product: labels,
+headings, helper text, button text, empty states, error messages, tooltips,
+notifications and confirmation dialogs.
+
+RULE: Content is product text. It is not marketing copy, and it does not live on
+this documentation site.
+
+## Who this section is for
+
+This section is for anyone at NaniSoft who writes text a customer will read:
+designers writing labels, engineers writing empty states and errors, product
+managers writing release notes, and support staff writing help text.
+
+RULE: Anyone who writes product copy MUST follow this section. It applies to
+first drafts as much as to reviews.
+
+## What this section is not
+
+This section is not a style guide for source code, commit messages or internal
+documents. Those have their own conventions. It is also not the design system's
+vocabulary; that is the [Glossary](/content/glossary).
+
+## The register
+
+RULE: This section MUST use RFC 2119 keywords (MUST, SHOULD, MAY) so a rule can
+be read unambiguously, and it MUST prefix each rule line with `RULE:` so the
+rules are machine-greppable.
+
+Outside this section, Prism write in plain language and avoid those keywords.
+The difference is deliberate: a rule that a reader must follow is stated as a
+rule, and everything else is explanation.

package/dist/md/content/audience.md

@@ -0,0 +1,43 @@
+# Audience
+
+The three people NaniSoft product copy serves, and what each one needs from a sentence.
+
+Product copy serves three audiences. A piece of text MUST land for the person who
+reads it in that moment, and the three do not always want the same thing.
+
+## The operator
+
+The operator uses the product to finish a job, often repeatedly. They know the
+interface and resent being told what they already know, but they need
+confirmation that a consequential action will do what they expect.
+
+- They read errors, confirmations and destructive-action warnings closely.
+- They skip onboarding and explanation.
+- RULE: For the operator, be brief and specific. State the consequence, not the
+  mechanism.
+
+## The evaluator
+
+The evaluator is deciding whether the product does what they need. They meet the
+product once, with a task in mind, and they are quick to leave.
+
+- They read empty states, first-run text and headings.
+- They need the next step to be obvious.
+- RULE: For the evaluator, name the outcome and give exactly one clear next
+  action.
+
+## The builder
+
+The builder integrates NaniSoft into something they own. They read documentation
+more than product copy, but the two meet in import errors, configuration screens
+and generated code.
+
+- They need exact names: packs, tokens, props and package paths.
+- They are unforgiving of a label that does not match the API.
+- RULE: For the builder, use the exact, cased term from the glossary. Do not
+  paraphrase a name of anything.
+
+## Reading level
+
+RULE: Write for a general professional audience. Prefer common words, active
+voice and a single idea per sentence.

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" />