prime-ui-kit 0.0.1

package/src/components/tooltip/examples/side.tsx

@@ -0,0 +1,69 @@
+import { Button, Label, Tooltip } from "prime-ui-kit";
+import type * as React from "react";
+
+import styles from "./examples.module.css";
+
+function TooltipDemoItem({ label, children }: { label: string; children: React.ReactNode }) {
+  return (
+    <div className={styles.demoItem}>
+      <Label.Root size="s">{label}</Label.Root>
+      {children}
+    </div>
+  );
+}
+
+/** `side` on `Tooltip.Content`: top, bottom, left, right (mirrors `playground/snippets/tooltip/side.tsx`). */
+export default function TooltipSideExample() {
+  return (
+    <>
+      <TooltipDemoItem label="Top">
+        <Tooltip.Provider delayDuration={200}>
+          <Tooltip.Root>
+            <Tooltip.Trigger>
+              <Button.Root type="button" variant="neutral" mode="stroke">
+                Hover
+              </Button.Root>
+            </Tooltip.Trigger>
+            <Tooltip.Content side="top">Content top</Tooltip.Content>
+          </Tooltip.Root>
+        </Tooltip.Provider>
+      </TooltipDemoItem>
+      <TooltipDemoItem label="Bottom">
+        <Tooltip.Provider delayDuration={200}>
+          <Tooltip.Root>
+            <Tooltip.Trigger>
+              <Button.Root type="button" variant="neutral" mode="stroke">
+                Hover
+              </Button.Root>
+            </Tooltip.Trigger>
+            <Tooltip.Content side="bottom">Content bottom</Tooltip.Content>
+          </Tooltip.Root>
+        </Tooltip.Provider>
+      </TooltipDemoItem>
+      <TooltipDemoItem label="Left">
+        <Tooltip.Provider delayDuration={200}>
+          <Tooltip.Root>
+            <Tooltip.Trigger>
+              <Button.Root type="button" variant="neutral" mode="stroke">
+                Hover
+              </Button.Root>
+            </Tooltip.Trigger>
+            <Tooltip.Content side="left">Content left</Tooltip.Content>
+          </Tooltip.Root>
+        </Tooltip.Provider>
+      </TooltipDemoItem>
+      <TooltipDemoItem label="Right">
+        <Tooltip.Provider delayDuration={200}>
+          <Tooltip.Root>
+            <Tooltip.Trigger>
+              <Button.Root type="button" variant="neutral" mode="stroke">
+                Hover
+              </Button.Root>
+            </Tooltip.Trigger>
+            <Tooltip.Content side="right">Content right</Tooltip.Content>
+          </Tooltip.Root>
+        </Tooltip.Provider>
+      </TooltipDemoItem>
+    </>
+  );
+}

package/src/components/tooltip/examples/sizes.tsx

@@ -0,0 +1,69 @@
+import { Button, Label, Tooltip } from "prime-ui-kit";
+import type * as React from "react";
+
+import styles from "./examples.module.css";
+
+function TooltipDemoItem({ label, children }: { label: string; children: React.ReactNode }) {
+  return (
+    <div className={styles.demoItem}>
+      <Label.Root size="s">{label}</Label.Root>
+      {children}
+    </div>
+  );
+}
+
+/** All four `Tooltip.Content` sizes on the same trigger button (mirrors `playground/snippets/tooltip/sizes.tsx`). */
+export default function TooltipSizesExample() {
+  return (
+    <>
+      <TooltipDemoItem label="Size s">
+        <Tooltip.Provider delayDuration={200}>
+          <Tooltip.Root>
+            <Tooltip.Trigger>
+              <Button.Root type="button" variant="neutral" mode="stroke" size="m">
+                Hover
+              </Button.Root>
+            </Tooltip.Trigger>
+            <Tooltip.Content size="s">Tooltip s</Tooltip.Content>
+          </Tooltip.Root>
+        </Tooltip.Provider>
+      </TooltipDemoItem>
+      <TooltipDemoItem label="Size m">
+        <Tooltip.Provider delayDuration={200}>
+          <Tooltip.Root>
+            <Tooltip.Trigger>
+              <Button.Root type="button" variant="neutral" mode="stroke" size="m">
+                Hover
+              </Button.Root>
+            </Tooltip.Trigger>
+            <Tooltip.Content size="m">Tooltip m</Tooltip.Content>
+          </Tooltip.Root>
+        </Tooltip.Provider>
+      </TooltipDemoItem>
+      <TooltipDemoItem label="Size l">
+        <Tooltip.Provider delayDuration={200}>
+          <Tooltip.Root>
+            <Tooltip.Trigger>
+              <Button.Root type="button" variant="neutral" mode="stroke" size="m">
+                Hover
+              </Button.Root>
+            </Tooltip.Trigger>
+            <Tooltip.Content size="l">Tooltip l</Tooltip.Content>
+          </Tooltip.Root>
+        </Tooltip.Provider>
+      </TooltipDemoItem>
+      <TooltipDemoItem label="Size xl">
+        <Tooltip.Provider delayDuration={200}>
+          <Tooltip.Root>
+            <Tooltip.Trigger>
+              <Button.Root type="button" variant="neutral" mode="stroke" size="m">
+                Hover
+              </Button.Root>
+            </Tooltip.Trigger>
+            <Tooltip.Content size="xl">Tooltip xl</Tooltip.Content>
+          </Tooltip.Root>
+        </Tooltip.Provider>
+      </TooltipDemoItem>
+    </>
+  );
+}

package/src/components/tooltip/examples/states.tsx

@@ -0,0 +1,57 @@
+import { Button, Label, Tooltip } from "prime-ui-kit";
+import type * as React from "react";
+
+import styles from "./examples.module.css";
+
+function Block({ label, children }: { label: string; children: React.ReactNode }) {
+  return (
+    <div className={styles.demoItem}>
+      <Label.Root size="s">{label}</Label.Root>
+      {children}
+    </div>
+  );
+}
+
+/** Default trigger, native disabled (tooltip does not open), glossary-style focus trigger (mirrors `playground/snippets/tooltip/states.tsx`). */
+export default function TooltipStatesExample() {
+  return (
+    <div className={styles.rowWrapXlJustifyCenter}>
+      <Block label="Default — hover and focus">
+        <Tooltip.Provider delayDuration={200}>
+          <Tooltip.Root>
+            <Tooltip.Trigger>
+              <Button.Root type="button" variant="neutral" mode="stroke">
+                Save
+              </Button.Root>
+            </Tooltip.Trigger>
+            <Tooltip.Content>Send the draft to the server</Tooltip.Content>
+          </Tooltip.Root>
+        </Tooltip.Provider>
+      </Block>
+      <Block label="Native disabled — hover does not open">
+        <Tooltip.Provider delayDuration={200}>
+          <Tooltip.Root>
+            <Tooltip.Trigger>
+              <Button.Root type="button" variant="neutral" mode="stroke" disabled>
+                Unavailable
+              </Button.Root>
+            </Tooltip.Trigger>
+            <Tooltip.Content>This copy does not appear on native disabled hover</Tooltip.Content>
+          </Tooltip.Root>
+        </Tooltip.Provider>
+      </Block>
+      <Block label="Keyboard focus — unstyled term button">
+        <Tooltip.Provider delayDuration={200}>
+          <Tooltip.Root>
+            <Tooltip.Trigger>
+              <button type="button" className={styles.inlineHelpTrigger}>
+                KPI
+              </button>
+            </Tooltip.Trigger>
+            <Tooltip.Content>Key performance indicator</Tooltip.Content>
+          </Tooltip.Root>
+        </Tooltip.Provider>
+      </Block>
+    </div>
+  );
+}

package/src/components/tooltip/examples/surfaces.tsx

@@ -0,0 +1,54 @@
+import { Button, Label, Tooltip } from "prime-ui-kit";
+import type { ReactNode } from "react";
+
+import styles from "./examples.module.css";
+
+function Panel({
+  label,
+  variant,
+  children,
+}: {
+  label: string;
+  variant: "default" | "raised";
+  children: ReactNode;
+}) {
+  const surfaceClass = variant === "default" ? styles.surfaceDefault : styles.surfaceRaised;
+  return (
+    <div className={`${styles.surfacePanel} ${surfaceClass}`}>
+      <Label.Root size="s">{label}</Label.Root>
+      {children}
+    </div>
+  );
+}
+
+/** Same tooltip chrome on `surface-default` vs `surface-raised` (mirrors `playground/snippets/tooltip/surfaces.tsx`). */
+export default function TooltipSurfacesExample() {
+  return (
+    <div className={styles.rowWrapMStretch}>
+      <Panel label="Surface default" variant="default">
+        <Tooltip.Provider delayDuration={200}>
+          <Tooltip.Root>
+            <Tooltip.Trigger>
+              <Button.Root type="button" variant="neutral" mode="stroke">
+                Hover
+              </Button.Root>
+            </Tooltip.Trigger>
+            <Tooltip.Content>Tooltip on neutral page background</Tooltip.Content>
+          </Tooltip.Root>
+        </Tooltip.Provider>
+      </Panel>
+      <Panel label="Surface raised" variant="raised">
+        <Tooltip.Provider delayDuration={200}>
+          <Tooltip.Root>
+            <Tooltip.Trigger>
+              <Button.Root type="button" variant="neutral" mode="stroke">
+                Hover
+              </Button.Root>
+            </Tooltip.Trigger>
+            <Tooltip.Content>Tooltip on a raised card surface</Tooltip.Content>
+          </Tooltip.Root>
+        </Tooltip.Provider>
+      </Panel>
+    </div>
+  );
+}

package/src/components/typography/COMPONENT.md

@@ -0,0 +1,127 @@
+# Typography
+
+**Default choice for page copy:** start from **`body-default`** in `variant` unless the scenario clearly needs another reading role.
+
+## About
+
+Styled text with **semantic reading roles** (`variant`) wired to `typography.role` in tokens, plus optional axes: `weight`, `tracking`, italic, and `tone` for secondary color. Renders as the HTML tag you pick with **`as`**.
+
+**When to use**
+
+- Body copy, headings, captions, and metrics where you want kit tokens instead of ad-hoc `font-size`.
+- `tone="muted"` for secondary explanations, hints, and legal lines.
+- Nested **`Typography.Root`** nodes with different `as` / `weight` inside one block (see `./examples/composition.tsx`, `./examples/05-inline-emphasis.tsx`).
+- `as="h1"`–`as="h6"` for heading levels that match the theme; keep a sensible outline order on the page.
+- `as` values that are landmarks (`main`, `article`, `section`, `header`, `footer`, …) when you need both semantics and typography on the same node — otherwise wrap landmarks in normal elements and put **`Typography.Root`** inside.
+
+**When not to use**
+
+- As a substitute for **button** or **link** chrome — use [Button](../button/COMPONENT.md) / [LinkButton](../link-button/COMPONENT.md).
+- Expecting a separate `line-height` control per instance — line height is part of the role in CSS.
+- Interactive controls (fields, switches, etc.) still use their own components and sizes; **Typography** does not restyle them.
+
+## Reference mapping: MD3, Apple (SF), Polaris
+
+Rough **hierarchy** alignment only — not pixel-perfect parity. Font size column assumes **`1rem = 16px`** on `:root` (rounded).
+
+| `variant` | Token step | ≈ px @16 | Close MD3 | Close Apple (SF) | Polaris `Text` |
+| --------- | ---------- | -------- | --------- | ---------------- | -------------- |
+| `display` | `9xl` | 57 | Display Large | Large Title | `heading3xl` |
+| `headline` | `6xl` | 32 | Headline Large | Title 1 | `heading2xl` |
+| `heading-page` | `4xl` | 28 | Headline Medium | Title 2 | `headingXl` |
+| `heading-section` | `2xl` | 24 | Headline Small | Title 3 | `headingLg` |
+| `heading-subsection` | `xl` | 22 | Title Large | Headline | `headingMd` |
+| `heading-group` | `xs` | 14 | Title Small | Subheadline / Footnote | `headingSm`, `headingXs` |
+| `body-large` | `s` | 16 | Body Large | Body / Callout | `bodyLg` |
+| `body-default` | `xs` | 14 | Body Medium | Subheadline | `bodyMd` |
+| `body-small` | `2xs` | 12 | Body Small | Footnote | `bodySm` |
+| `body-compact` | `xs` size, tighter line | 14 | Label Large (dense) | — | `bodyXs` |
+| `caption` | `2xs` | 12 | Label Medium | Caption 1 | `bodySm` (with `tone`) |
+| `caption-micro` | `labelMicro` | 11 | Label Small | Caption 2 | smallest semantic step |
+
+Steps **`7xl`** / **`8xl`** exist in the scale but are **not** wired to `typography.role` — use tokens directly if you need them, not **`Typography`**.
+
+## Composition
+
+- Single primitive: **`Typography.Root`**. Put text or inline markup in **`children`**.
+- **`as`** defaults to **`p`**; allowed: paragraph, inline, block, **`h1`–`h6`**, **`small`**, **`blockquote`**, landmarks (`article`, `section`, `header`, `footer`, `aside`, `nav`, `main`).
+
+### Canonical example
+
+```tsx
+import { Typography } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <>
+      <Typography.Root as="h1" variant="heading-page">
+        Release notes
+      </Typography.Root>
+      <Typography.Root as="p" variant="body-default" tone="muted">
+        Summary of changes for the current shipping cycle.
+      </Typography.Root>
+      <Typography.Root as="p" variant="body-default">
+        Copy uses reading roles; controls use their own size scale — keep both axes explicit in layouts.
+      </Typography.Root>
+    </>
+  );
+}
+```
+
+### Playground-aligned examples
+
+Order matches **`playground/sections/TypographySection.tsx`** and the runnable snippets in **`playground/snippets/typography/`**; the same scenarios ship under **`./examples/`** for `prime-ui-kit` consumers (import from **`prime-ui-kit`**).
+
+| Playground snippet | Package example |
+| --- | --- |
+| [`variant-catalog.tsx`](../../../playground/snippets/typography/variant-catalog.tsx) | [`./examples/variant-catalog.tsx`](./examples/variant-catalog.tsx) |
+| [`article-landmarks.tsx`](../../../playground/snippets/typography/article-landmarks.tsx) | [`./examples/01-article.tsx`](./examples/01-article.tsx) (same structure; English copy) |
+| [`reading-and-form.tsx`](../../../playground/snippets/typography/reading-and-form.tsx) | [`./examples/reading-and-form.tsx`](./examples/reading-and-form.tsx) |
+| [`variants.tsx`](../../../playground/snippets/typography/variants.tsx) | [`./examples/variants.tsx`](./examples/variants.tsx) |
+| [`states.tsx`](../../../playground/snippets/typography/states.tsx) | [`./examples/states.tsx`](./examples/states.tsx) |
+| [`composition.tsx`](../../../playground/snippets/typography/composition.tsx) | [`./examples/composition.tsx`](./examples/composition.tsx) |
+| [`full-width.tsx`](../../../playground/snippets/typography/full-width.tsx) | [`./examples/full-width.tsx`](./examples/full-width.tsx) |
+| [`as-prop.tsx`](../../../playground/snippets/typography/as-prop.tsx) | [`./examples/as-prop.tsx`](./examples/as-prop.tsx) |
+
+### Additional examples
+
+- [`./examples/02-form-labels-contrast.tsx`](./examples/02-form-labels-contrast.tsx) — **`Input`** label / optional / hint slots built with **`Typography.Root`** (richer than the playground form frame).
+- [`./examples/03-marketing-hero.tsx`](./examples/03-marketing-hero.tsx) — Hero stack: caption, display, headline, muted body.
+- [`./examples/04-reading-scale.tsx`](./examples/04-reading-scale.tsx) — Compact English ladder of every **`variant`** (no **`Divider`** captions; use **`variant-catalog`** for the full labeled catalog).
+- [`./examples/05-inline-emphasis.tsx`](./examples/05-inline-emphasis.tsx) — Nested spans on **`body-default`** (English; playground **`composition`** adds a link and `as="div"` wrapper).
+
+**LLM note:** Use **`./examples/*.tsx`** for copy-paste scenarios; **`playground/snippets/typography/*.tsx`** stay the source shown in the dev playground (`?raw`). This page keeps the contract (rules + API tables) authoritative.
+
+## Rules
+
+- **`variant` is required**; default-looking props omit extra **`data-*`** (`weight="regular"`, `tracking="normal"`, `tone="default"`, no italic).
+- DOM: **`data-variant`** uses kebab-case (e.g. `heading-page`).
+- Standard HTML attributes (`id`, `aria-*`, …) pass through **`...rest`**.
+- Root uses **`text-wrap: balance`** on short blocks; override from a parent if needed.
+- No built-in disabled / loading / error states — combine with surrounding UI.
+
+## API
+
+### Typography.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| as | see `TypographyAs` | `"p"` | No | HTML element |
+| variant | see `TypographyVariant` | — | Yes | Reading role |
+| weight | `"regular"` \| `"medium"` \| `"semibold"` | `"regular"` | No | Font weight |
+| tracking | `"normal"` \| `"tight"` \| `"tighter"` \| `"wide"` | `"normal"` | No | Letter spacing |
+| italic | `boolean` | `false` | No | Italic |
+| tone | `"default"` \| `"muted"` | `"default"` | No | Primary vs secondary text color |
+| children | `React.ReactNode` | — | No | Content |
+| className | `string` | — | No | Extra class |
+| ref | `React.Ref<HTMLElement>` | — | No | Element ref |
+| …rest | `React.HTMLAttributes<HTMLElement>` | — | No | Other element props |
+
+## Related
+
+- [Label](../label/COMPONENT.md)
+- [Hint](../hint/COMPONENT.md)
+- [Input](../input/COMPONENT.md)
+- [LinkButton](../link-button/COMPONENT.md)
+- [Banner](../banner/COMPONENT.md)
+- [Notification](../notification/COMPONENT.md)

package/src/components/typography/examples/01-article.tsx

@@ -0,0 +1,45 @@
+import { Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Long-form article: landmarks, heading levels, pull quote — all copy via Typography.Root.
+ */
+export default function TypographyExampleArticle() {
+  return (
+    <article className={styles.stack}>
+      <header className={styles.stackTight}>
+        <Typography.Root as="h1" variant="heading-page">
+          Designing readable product surfaces
+        </Typography.Root>
+        <Typography.Root as="p" variant="body-default" tone="muted">
+          Semantic reading roles map to theme tokens; avoid ad-hoc font sizes for page text.
+        </Typography.Root>
+      </header>
+      <section aria-labelledby="article-section-roles">
+        <Typography.Root id="article-section-roles" as="h2" variant="heading-section">
+          Roles vs control sizes
+        </Typography.Root>
+        <Typography.Root as="p" variant="body-default">
+          Page typography uses <code>variant</code>; buttons and fields use their own{" "}
+          <code>size</code> axis — keep both visible on the same screen without fighting the same
+          scale.
+        </Typography.Root>
+      </section>
+      <section aria-labelledby="article-section-quote">
+        <Typography.Root id="article-section-quote" as="h2" variant="heading-section">
+          Pull quote
+        </Typography.Root>
+        <blockquote className={styles.stackTight}>
+          <Typography.Root as="p" variant="body-large">
+            When labels read as body and hints read as captions, users scan forms faster and make
+            fewer mistakes.
+          </Typography.Root>
+          <Typography.Root as="footer" variant="caption" tone="muted">
+            — Internal UX writing guide
+          </Typography.Root>
+        </blockquote>
+      </section>
+    </article>
+  );
+}

package/src/components/typography/examples/02-form-labels-contrast.tsx

@@ -0,0 +1,61 @@
+import { Input, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Form context: label text vs optional tag vs hint — Typography.Root for each string role
+ * (Input still owns the field chrome; see Input COMPONENT.md).
+ */
+export default function TypographyExampleFormLabelsContrast() {
+  return (
+    <div className={styles.stack}>
+      <Typography.Root as="h1" variant="heading-page">
+        Workspace settings
+      </Typography.Root>
+      <Typography.Root as="p" variant="body-default" tone="muted">
+        Stronger weight on the label, smaller muted lines for hints, so the eye lands on the field
+        name first.
+      </Typography.Root>
+      <div className={styles.formFields}>
+        <Input.Root
+          id="typography-example-email"
+          label={
+            <Typography.Root as="span" variant="body-compact" weight="semibold">
+              Work email
+            </Typography.Root>
+          }
+          hint={
+            <Typography.Root as="span" variant="caption" tone="muted">
+              Invoices and security alerts only; never shared with vendors.
+            </Typography.Root>
+          }
+        >
+          <Input.Wrapper>
+            <Input.Field type="email" autoComplete="email" placeholder="you@company.com" />
+          </Input.Wrapper>
+        </Input.Root>
+        <Input.Root
+          label={
+            <Typography.Root as="span" variant="body-default" weight="medium">
+              Display name
+            </Typography.Root>
+          }
+          optionalLabel={
+            <Typography.Root as="span" variant="caption" tone="muted">
+              optional
+            </Typography.Root>
+          }
+          hint={
+            <Typography.Root as="span" variant="body-small" tone="muted">
+              Shown to teammates; use your full name or a short handle.
+            </Typography.Root>
+          }
+        >
+          <Input.Wrapper>
+            <Input.Field placeholder="Alex Chen" />
+          </Input.Wrapper>
+        </Input.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/typography/examples/03-marketing-hero.tsx

@@ -0,0 +1,25 @@
+import { Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Marketing hero stack: display → body → muted supporting line — Typography.Root only. */
+export default function TypographyExampleMarketingHero() {
+  return (
+    <div className={styles.hero}>
+      <Typography.Root as="p" variant="caption" tone="muted" tracking="wide">
+        NEW — AUTOMATION SUITE
+      </Typography.Root>
+      <Typography.Root as="h1" variant="display">
+        Ship workflows your team actually uses
+      </Typography.Root>
+      <Typography.Root as="p" variant="headline" weight="regular">
+        Connect tools, approvals, and notifications in one place — without ripping out what already
+        works.
+      </Typography.Root>
+      <Typography.Root as="p" variant="body-large" tone="muted">
+        Free trial for 14 days. No card required. SOC 2 Type II and regional data residency
+        available on request.
+      </Typography.Root>
+    </div>
+  );
+}

package/src/components/typography/examples/04-reading-scale.tsx

@@ -0,0 +1,47 @@
+import { Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Vertical ladder of reading roles from display down to caption-micro (English labels). */
+export default function TypographyExampleReadingScale() {
+  return (
+    <div className={styles.scaleList}>
+      <Typography.Root as="p" variant="display">
+        Display
+      </Typography.Root>
+      <Typography.Root as="p" variant="headline">
+        Headline
+      </Typography.Root>
+      <Typography.Root as="p" variant="heading-page">
+        Heading page
+      </Typography.Root>
+      <Typography.Root as="p" variant="heading-section">
+        Heading section
+      </Typography.Root>
+      <Typography.Root as="p" variant="heading-subsection">
+        Heading subsection
+      </Typography.Root>
+      <Typography.Root as="p" variant="heading-group">
+        Heading group
+      </Typography.Root>
+      <Typography.Root as="p" variant="body-large">
+        Body large — introductory paragraphs and emphasis blocks.
+      </Typography.Root>
+      <Typography.Root as="p" variant="body-default">
+        Body default — default paragraph role for product copy.
+      </Typography.Root>
+      <Typography.Root as="p" variant="body-small">
+        Body small — dense tables and secondary descriptions.
+      </Typography.Root>
+      <Typography.Root as="p" variant="body-compact">
+        Body compact — tight single-line labels and metadata.
+      </Typography.Root>
+      <Typography.Root as="p" variant="caption">
+        Caption — supporting text and timestamps.
+      </Typography.Root>
+      <Typography.Root as="p" variant="caption-micro" tone="muted">
+        Caption micro — legal footnotes and fine print.
+      </Typography.Root>
+    </div>
+  );
+}

package/src/components/typography/examples/05-inline-emphasis.tsx

@@ -0,0 +1,30 @@
+import { Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Nested Typography.Root spans inside one paragraph: weight and tracking without new variants. */
+export default function TypographyExampleInlineEmphasis() {
+  return (
+    <div className={styles.stack}>
+      <Typography.Root as="p" variant="body-default">
+        Order{" "}
+        <Typography.Root as="span" variant="body-default" weight="semibold">
+          #4821
+        </Typography.Root>{" "}
+        is{" "}
+        <Typography.Root as="span" variant="body-default" weight="medium" tracking="tight">
+          out for delivery
+        </Typography.Root>
+        . Total{" "}
+        <Typography.Root as="span" variant="body-default" weight="medium">
+          $124.00
+        </Typography.Root>
+        ; estimated arrival{" "}
+        <Typography.Root as="span" variant="body-default" tone="muted">
+          Tue, Apr 2
+        </Typography.Root>
+        .
+      </Typography.Root>
+    </div>
+  );
+}

package/src/components/typography/examples/as-prop.tsx

@@ -0,0 +1,25 @@
+import { Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Проп `as`: `p`, `div`, вложенный `span`. Зеркало `playground/snippets/typography/as-prop.tsx`. */
+export default function TypographyExampleAsProp() {
+  return (
+    <div className={styles.typographyScaleList}>
+      <Typography.Root as="p" variant="body-default">
+        as=&quot;p&quot; — отдельный абзац с нулевыми внешними отступами по умолчанию у компонента.
+      </Typography.Root>
+      <Typography.Root as="div" variant="body-default">
+        as=&quot;div&quot; — блочный контейнер, если нужна обёртка без семантики абзаца (например
+        внутри карточки).
+      </Typography.Root>
+      <Typography.Root as="p" variant="body-default">
+        В одной строке можно вставить{" "}
+        <Typography.Root as="span" variant="body-default" weight="semibold">
+          span с акцентом
+        </Typography.Root>{" "}
+        без нового абзаца.
+      </Typography.Root>
+    </div>
+  );
+}

package/src/components/typography/examples/composition.tsx

@@ -0,0 +1,29 @@
+import { Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Вложенные `Typography.Root` и ссылка внутри блока.
+ * Зеркало `playground/snippets/typography/composition.tsx`.
+ */
+export default function TypographyExampleComposition() {
+  return (
+    <div className={styles.typographyScaleList}>
+      <Typography.Root variant="body-default" as="div">
+        Сводка по заказу № 4821: статус{" "}
+        <Typography.Root as="span" variant="body-default" weight="semibold">
+          отправлен
+        </Typography.Root>
+        . Сумма{" "}
+        <Typography.Root as="span" variant="body-default" weight="medium" tracking="tight">
+          12 400 ₽
+        </Typography.Root>
+        , доставка до{" "}
+        <a href="#typography-example-composition" className={styles.inlineLinkInherit}>
+          уточнить адрес
+        </a>
+        . Подробности — в разделе «История покупок».
+      </Typography.Root>
+    </div>
+  );
+}