@nanisoft/prism-llms 0.4.0 → 0.5.0

package/dist/md/components/alert.md

@@ -1,14 +1,97 @@
 # Alert
 
-antd Alert, unchanged — a pass-through re-export. Import from '@nanisoft/prism-ui'.
+A static callout that carries an important message to the reader.
 
-```ts
-import { Alert } from '@nanisoft/prism-ui/components';
+```tsx
+import { Alert, AlertTitle, AlertDescription } from '@nanisoft/prism-ui/components/alert'
 ```
 
-`Alert` is antd's [Alert](https://ant.design/components/alert), re-exported unchanged.
+## Overview
 
-- Extends: antd **Alert** — for inherited props and demos, use the antd MCP (`antd_info Alert`).
-- Always import from '@nanisoft/prism-ui', never from `antd` directly.
+An Alert is a static callout that carries an important message in place. It
+ships as `Alert`, `AlertTitle` and `AlertDescription`, all from the same module.
 
-_No additional props beyond the antd base component._
+The root renders a `<div role="alert">`, so assistive technology announces it
+when it enters the document. `variant="destructive"` switches the border and
+text to the destructive token for an error; the default is the neutral surface.
+The icon, when one is passed as the first child, is placed beside the text and
+takes the variant's colour.
+
+## Guidelines
+
+### When to use
+
+Use an Alert for a message that must be read before the reader continues: a
+failed publish, a failed connection, a maintenance window, a consequence of the
+action they are about to take.
+
+### When not to use
+
+Do not use an Alert for a transient success. A message that confirms something
+happened should not occupy the page afterwards; a toast covers that case, and
+toasts are not in v1.
+
+Do not use an Alert for a field-level problem. A FieldError sits beside the
+control it belongs to.
+
+Do not use an Alert for a decision the reader must make before continuing. A
+dialog blocks the page and takes focus; an inline callout does neither.
+
+### Best practices
+
+- Lead with the condition in `AlertTitle` and put the next step in
+  `AlertDescription`. A reader scanning the page should get the point from the
+  title alone.
+- Keep the whole callout to two short sentences. Anything longer is documentation
+  and belongs in the page body.
+- Reserve `variant="destructive"` for a real failure. Using it for a warning
+  spends the one emphasis the system has.
+- Pair the colour with the word. The title carries the meaning; the variant
+  reinforces it.
+- Mark a decorative icon `aria-hidden` so it does not enter the announced text,
+  and never use the icon as the only signal of severity.
+- Place any action the message calls for just after the callout, not inside the
+  description, so the reading order stays simple.
+
+### Content guidelines
+
+- State the condition and the next step: "Publish failed. Fix the type error and
+  publish again."
+- Do not prefix the title with "Error" or "Warning". The variant and the words
+  already say it.
+- Use sentence case and no period in the title. The description takes full
+  sentences.
+
+**The neutral alert beside the destructive one.**
+
+```tsx
+import {
+  Alert,
+  AlertDescription,
+  AlertTitle,
+} from '@nanisoft/prism-ui/components/alert'
+
+/** The neutral alert beside the destructive one. */
+export default function AlertDemo() {
+  return (
+    <div className="flex flex-col gap-4">
+      <Alert>
+        <AlertTitle>Scheduled maintenance</AlertTitle>
+        <AlertDescription>
+          Reads stay available on 3 October between 02:00 and 04:00.
+        </AlertDescription>
+      </Alert>
+      <Alert variant="destructive">
+        <AlertTitle>Publish failed</AlertTitle>
+        <AlertDescription>
+          The build did not finish. Fix the type error and publish again.
+        </AlertDescription>
+      </Alert>
+    </div>
+  )
+}
+```
+
+## Props
+
+**`variant`** `"default" | "destructive" | null | undefined` · optional · default: —

package/dist/md/components/avatar.md

@@ -1,14 +1,96 @@
 # Avatar
 
-antd Avatar, unchanged — a pass-through re-export. Import from '@nanisoft/prism-ui'.
+The person or entity image with an initials fallback.
 
-```ts
-import { Avatar } from '@nanisoft/prism-ui/components';
+```tsx
+import { Avatar, AvatarImage, AvatarFallback } from '@nanisoft/prism-ui/components/avatar'
 ```
 
-`Avatar` is antd's [Avatar](https://ant.design/components/avatar), re-exported unchanged.
+## Overview
 
-- Extends: antd **Avatar** — for inherited props and demos, use the antd MCP (`antd_info Avatar`).
-- Always import from '@nanisoft/prism-ui', never from `antd` directly.
+An Avatar shows a person or entity's image, with an initials fallback when the
+image is missing or still loading. It ships as `Avatar`, `AvatarImage` and
+`AvatarFallback`, all from the same module. The fallback covers the moment
+before the image arrives and the case where it never does, so the control is
+never an empty circle.
 
-_No additional props beyond the antd base component._
+Size the root with `className`; the image and the fallback fill it. The image is
+a real `<img>`, so give it a meaningful `alt`, or leave `alt` empty when the
+adjacent name already identifies the person.
+
+## Guidelines
+
+### When to use
+
+Use an Avatar to represent a person or an entity in a list, a header, a comment
+or a member row, where a face or initials helps the reader identify the subject
+at a glance.
+
+### When not to use
+
+Do not use an Avatar as a control on its own. A clickable avatar is a Button or
+a link; wrap the Avatar rather than making the image interactive.
+
+Do not use one when the name alone is enough, such as a single signed-in user's
+own settings page. The name carries the meaning; the image adds noise.
+
+Do not use an Avatar for a decorative mark. A logo or an icon tile is a
+different job.
+
+### Best practices
+
+- Always render an `AvatarFallback`. Without it, a slow or missing image leaves
+  an empty circle.
+- Keep the fallback to one or two initials, derived from the name, and set
+  `text-xs` or smaller on a small avatar.
+- Give the image a name when it stands alone, and an empty `alt` when the name
+  sits beside it, so a screen reader does not read it twice.
+- Use one size per context. A list of avatars at mixed sizes makes the rows
+  harder to compare.
+- Do not encode status in the avatar alone. A presence dot needs a text
+  alternative nearby.
+
+### Content guidelines
+
+- Fall back to initials, not a generic icon, so the circle still identifies the
+  person.
+- Use the same name form in the fallback as in the adjacent label, so the two
+  read as one subject.
+- Keep the `alt` text to the person's name, without titles or roles.
+
+**Avatars with an image, initials fallbacks and a smaller size.**
+
+```tsx
+import { Avatar, AvatarFallback, AvatarImage } from '@nanisoft/prism-ui/components/avatar'
+
+const portrait =
+  "data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' width='80' height='80'><rect width='80' height='80' fill='%23111827'/><circle cx='40' cy='30' r='14' fill='%2394a3b8'/><rect x='16' y='50' width='48' height='40' rx='20' fill='%2394a3b8'/></svg>"
+
+/** Avatars with an image, initials fallbacks and a smaller size. */
+export default function AvatarDemo() {
+  return (
+    <div className="flex items-center gap-4">
+      <Avatar>
+        <AvatarImage src={portrait} alt="" />
+        <AvatarFallback>AL</AvatarFallback>
+      </Avatar>
+      <Avatar>
+        <AvatarFallback>PR</AvatarFallback>
+      </Avatar>
+      <Avatar className="size-8">
+        <AvatarFallback className="text-xs">SM</AvatarFallback>
+      </Avatar>
+      <Avatar className="size-12">
+        <AvatarImage src={portrait} alt="Ada Lovelace" />
+        <AvatarFallback>AL</AvatarFallback>
+      </Avatar>
+    </div>
+  )
+}
+```
+
+## Props
+
+**`onLoadingStatusChange`** `(status: 'idle' | 'loading' | 'loaded' | 'error') => void` · optional · default: — — Called when the image loading status changes.
+**`keepMounted`** `boolean` · optional · default: `false` — Whether the image stays mounted and loads in place.
+**`delay`** `number` · optional · default: `0` — How long to wait before showing the fallback, in milliseconds.

package/dist/md/components/badge.md

@@ -1,14 +1,81 @@
 # Badge
 
-antd Badge, unchanged — a pass-through re-export. Import from '@nanisoft/prism-ui'.
+A compact status or category label.
 
-```ts
-import { Badge } from '@nanisoft/prism-ui/components';
+```tsx
+import { Badge } from '@nanisoft/prism-ui/components/badge'
 ```
 
-`Badge` is antd's [Badge](https://ant.design/components/badge), re-exported unchanged.
+## Overview
 
-- Extends: antd **Badge** — for inherited props and demos, use the antd MCP (`antd_info Badge`).
-- Always import from '@nanisoft/prism-ui', never from `antd` directly.
+A Badge is a compact label for a short status or category. It renders a
+`<span>` with a filled or outlined surface, and it is not interactive: it
+carries meaning next to something else rather than being a control itself.
 
-_No additional props beyond the antd base component._
+`variant` selects the surface treatment. `default` is the neutral filled badge,
+`secondary` is a quieter fill, `outline` is a bordered badge for a surface that
+already has a fill, and `destructive`, `success` and `warning` carry the three
+status colours.
+
+## Guidelines
+
+### When to use
+
+Use a Badge to mark a row, a card or a heading with one short fact: a status, a
+plan name, a count or a category.
+
+### When not to use
+
+Do not use a Badge as a control. It does not take focus and it does not respond
+to a press; use a Button for an action and a link for navigation.
+
+Do not use a Badge for a sentence or a long phrase. A badge is a label, and a
+label that wraps stops reading as one.
+
+Do not use `destructive`, `success` or `warning` for decoration. Those three
+carry status meaning, and colour alone never carries it for a reader who cannot
+distinguish it.
+
+### Best practices
+
+- Pair the colour with the word. A status is communicated by the label first;
+  the variant reinforces it.
+- Use at most one status Badge per row. Two statuses on one row make the reader
+  decide which is current.
+- Keep the variant to a small, consistent set across a product, so `success`
+  always means the same thing.
+- Place a status Badge beside the name it qualifies, not at the far edge of the
+  row where it can be read as belonging to a neighbour.
+
+### Content guidelines
+
+- Keep a Badge to one or two words.
+- Use sentence case: "Past due", not "Past Due".
+- Prefer a noun or an adjective. "Active" and "Trial" read as states; "Started"
+  reads as an action that already happened.
+- Do not invent a status the product does not have. If the set is unclear, the
+  status vocabulary belongs above the component.
+
+**Badge at each variant, paired with the word that carries the status.**
+
+```tsx
+import { Badge } from '@nanisoft/prism-ui/components/badge'
+
+/** Badge at each variant, paired with the word that carries the status. */
+export default function BadgeDemo() {
+  return (
+    <div className="flex flex-wrap items-center gap-3">
+      <Badge>New</Badge>
+      <Badge variant="secondary">Draft</Badge>
+      <Badge variant="outline">Internal</Badge>
+      <Badge variant="success">Active</Badge>
+      <Badge variant="warning">Past due</Badge>
+      <Badge variant="destructive">Failed</Badge>
+    </div>
+  )
+}
+```
+
+## Props
+
+**`variant`** `"default" | "destructive" | "outline" | "secondary" | "success" | "warning" | null | undefined` · optional · default: —

package/dist/md/components/breadcrumb.md

@@ -1,14 +1,91 @@
 # Breadcrumb
 
-antd Breadcrumb, unchanged — a pass-through re-export. Import from '@nanisoft/prism-ui'.
+The trail of ancestor links that shows where the current page sits.
 
-```ts
-import { Breadcrumb } from '@nanisoft/prism-ui/components';
+```tsx
+import { Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator } from '@nanisoft/prism-ui/components/breadcrumb'
 ```
 
-`Breadcrumb` is antd's [Breadcrumb](https://ant.design/components/breadcrumb), re-exported unchanged.
+## Overview
 
-- Extends: antd **Breadcrumb** — for inherited props and demos, use the antd MCP (`antd_info Breadcrumb`).
-- Always import from '@nanisoft/prism-ui', never from `antd` directly.
+A Breadcrumb shows the reader where the current page sits in a hierarchy and
+offers a way back up it. It ships as a parent and five parts: `Breadcrumb`,
+`BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage` and
+`BreadcrumbSeparator`, all from the same module.
 
-_No additional props beyond the antd base component._
+The parts keep the native list semantics a screen reader expects. `Breadcrumb`
+is a labelled `<nav>`, `BreadcrumbList` is an `<ol>`, and each `BreadcrumbItem`
+is an `<li>`. The last item is a `BreadcrumbPage`, which renders text carrying
+`aria-current="page"` rather than a dead link. Separators are decorative and
+hidden from assistive technology, so the trail reads as a list of destinations
+instead of a list of glyphs.
+
+## Guidelines
+
+### When to use
+
+Use a Breadcrumb when the reader can be more than one step deep: a catalog item
+inside a category, a record inside a project, or a settings page inside an
+account. It answers two questions at once, which section this page belongs to
+and how to leave it.
+
+### When not to use
+
+Do not use a Breadcrumb on a top-level page. A trail with one step restates the
+page title and adds nothing.
+
+Do not use it as the page's primary navigation. A Breadcrumb is a secondary
+affordance; the header or side navigation still owns the main routes.
+
+Do not use it to model a linear flow. A checkout or a wizard moves forward and
+back in a fixed order, so previous and next controls express that better.
+
+### Best practices
+
+- Ship one Breadcrumb per page and place it above the page title.
+- Link every ancestor and render only the current page as plain text with
+  `aria-current="page"`. A link to the page you are already on wastes a stop.
+- Keep the labels the same as the destinations they point at, so the trail
+  matches the navigation the reader came from.
+- Let the trail wrap rather than truncate the middle. A label a reader cannot
+  finish reading is not a label.
+- Use `BreadcrumbSeparator`'s default chevron and leave it decorative. If a
+  separator carries meaning in the copy, it belongs in the link text instead.
+
+**A three-level trail with the current page marked.**
+
+```tsx
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from '@nanisoft/prism-ui/components/breadcrumb'
+
+/** A three-level trail with the current page marked. */
+export default function BreadcrumbDemo() {
+  return (
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>
+          <BreadcrumbLink href="/">Home</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbLink href="/components">Components</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
+        </BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+  )
+}
+```
+
+## Props
+
+> Extends: the native `<nav>` element. No additional Prism-specific props.

package/dist/md/components/button.md

@@ -1,14 +1,97 @@
 # Button
 
-antd Button, unchanged — a pass-through re-export. Import from '@nanisoft/prism-ui'.
+The action control for commands, links and loading states.
 
-```ts
-import { Button } from '@nanisoft/prism-ui/components';
+```tsx
+import { Button } from '@nanisoft/prism-ui/components/button'
 ```
 
-`Button` is antd's [Button](https://ant.design/components/button), re-exported unchanged.
+## Overview
 
-- Extends: antd **Button** — for inherited props and demos, use the antd MCP (`antd_info Button`).
-- Always import from '@nanisoft/prism-ui', never from `antd` directly.
+The Button is the control for an action the reader takes deliberately. It
+renders a native `<button>` and takes the standard React button props plus
+`variant` and `size`, so it behaves like the element it is: it submits, it is
+focusable, and it is reachable by keyboard without extra work.
 
-_No additional props beyond the antd base component._
+The `variant` prop carries the action hierarchy. `default` is the primary
+action, `secondary` and `outline` are supporting actions, `ghost` is for a quiet
+action inside a surface that already carries weight, `destructive` marks an
+action that cannot be undone, and `link` is an action styled as a link for the
+rare case where an action sits inside a sentence.
+
+## Guidelines
+
+### When to use
+
+Use a Button when the reader's intent is to make something happen: submit a
+form, save a change, delete a record, open a dialog, or start a process.
+
+Use one `default` Button per view for the action the view exists to perform.
+Supporting actions take `secondary` or `outline`.
+
+### When not to use
+
+Do not use a Button to navigate. A route change is a link, and a link is
+right-clickable, openable in a new tab, and announced as a link. Use an anchor
+with the link styling instead.
+
+Do not use a `ghost` Button as the only affordance on an empty surface. With no
+surface to sit against, a ghost control reads as text; use `outline`.
+
+Do not use a `destructive` Button for an action that can be undone. Reserve it
+for the action that cannot.
+
+### Best practices
+
+- Keep one `default` Button visible at a time. Two primaries make neither of
+  them primary.
+- Put the primary action last in reading order in a left-to-right layout, after
+  the supporting actions.
+- For a destructive action, put the consequence in the confirmation, not in the
+  button label. The label names the thing, not the warning.
+- A loading or disabled Button should explain why it is unavailable through
+  adjacent text or a tooltip. A disabled control with no reason in reach is a
+  dead end.
+- The coarse-pointer media query grows the target to 44px on touch input
+  automatically. Do not add a second size rule for touch.
+
+### Content guidelines
+
+- Start a label with a verb in the imperative: "Save", "Delete project", "Add member".
+- Use sentence case and no period.
+- Name the object when the action is ambiguous: "Delete project" is better than
+  "Delete".
+- Never use "Click here" or "Submit". The button's own label should state its
+  outcome.
+- Keep a label to three words where possible.
+
+**Buttons at each variant and size.**
+
+```tsx
+import { Button } from '@nanisoft/prism-ui/components/button'
+
+/**
+ * Buttons at each variant and size.
+ *
+ * Self-contained: the only import is from the package, and it has a default
+ * export. The file is the source for the live preview, the copy control and the
+ * corpus.
+ */
+export default function ButtonDemo() {
+  return (
+    <div className="flex flex-wrap items-center gap-3">
+      <Button>Save changes</Button>
+      <Button variant="secondary">Secondary</Button>
+      <Button variant="outline">Cancel</Button>
+      <Button variant="ghost">Ghost</Button>
+      <Button variant="destructive">Delete project</Button>
+      <Button variant="link">Read the guide</Button>
+    </div>
+  )
+}
+```
+
+## Props
+
+**`variant`** `"default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | null | undefined` · optional · default: —
+**`size`** `"default" | "sm" | "lg" | "icon" | null | undefined` · optional · default: —

package/dist/md/components/card.md

@@ -1,14 +1,97 @@
 # Card
 
-antd Card, unchanged — a pass-through re-export. Import from '@nanisoft/prism-ui'.
+A bordered surface for a small group of related content.
 
-```ts
-import { Card } from '@nanisoft/prism-ui/components';
+```tsx
+import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@nanisoft/prism-ui/components/card'
 ```
 
-`Card` is antd's [Card](https://ant.design/components/card), re-exported unchanged.
+## Overview
 
-- Extends: antd **Card** — for inherited props and demos, use the antd MCP (`antd_info Card`).
-- Always import from '@nanisoft/prism-ui', never from `antd` directly.
+A Card is a bordered surface that groups a small set of related content. It
+ships as a parent and five parts: `Card`, `CardHeader`, `CardTitle`,
+`CardDescription`, `CardContent` and `CardFooter`, all from the same module.
 
-_No additional props beyond the antd base component._
+The parts are optional and their order is the reading order. A card with a title
+and a body uses `CardHeader`, `CardTitle` and `CardContent`; a card that ends in
+an action adds `CardFooter`.
+
+## Guidelines
+
+### When to use
+
+Use a Card when a small group of related content needs a shared boundary: a
+summary tile, a settings group, a list item with a title and a body, or one item
+in a grid.
+
+### When not to use
+
+Do not use a Card for the page's own frame. A Card inside a Card, or a Card used
+as a section wrapper, produces a border inside a border and flattens the
+hierarchy. Use `Section` for page rhythm.
+
+Do not use a Card for a single field or a single line of text. A boundary around
+one thing adds weight without grouping anything.
+
+Do not use a Card as a link by wrapping it in an anchor with a nested button. If
+the whole card is navigable, make the title the link and keep any action a
+sibling of it.
+
+### Best practices
+
+- Use one heading per card. `CardTitle` is a title, not a second heading level
+  in the page outline; the card's own section provides that.
+- Keep `CardDescription` to a single sentence. A paragraph belongs in
+  `CardContent`.
+- Put the card's action in `CardFooter` so a grid of cards aligns its actions on
+  one line.
+- In a grid, make cards the same height and keep the action at the end, so the
+  eye can compare rows.
+
+### Content guidelines
+
+- A title is a noun phrase and takes sentence case: "Release notes", not
+  "Release Notes".
+- A description states what the group is, not what to do with it.
+- A footer action uses the same verb-first, sentence-case rule as a Button
+  label.
+
+**A card with a header, a body and a footer action.**
+
+```tsx
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+} from '@nanisoft/prism-ui/components/card'
+import { Button } from '@nanisoft/prism-ui/components/button'
+
+/** A card with a header, a body and a footer action. */
+export default function CardDemo() {
+  return (
+    <Card className="max-w-sm">
+      <CardHeader>
+        <CardTitle>Release 2.4</CardTitle>
+        <CardDescription>Shipped to production on 12 August.</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <p className="text-muted-foreground text-sm">
+          Three fixes and one new block, with no token changes.
+        </p>
+      </CardContent>
+      <CardFooter>
+        <Button variant="outline" size="sm">
+          View changelog
+        </Button>
+      </CardFooter>
+    </Card>
+  )
+}
+```
+
+## Props
+
+> Extends: the native `<div>` element. No additional Prism-specific props.