prime-ui-kit 0.9.0 → 0.9.2

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

@@ -1,22 +1,17 @@
-/** Key caps in the five badge tiers: 16 · 20 · 24 · 28 · 32 px, default `m`. Use an explicit size for standalone shortcuts in text and docs. */
+/** Every badge tier, 16 to 32 px high — `size`. */
 import { Kbd, Typography } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
-const sizes = ["xs", "s", "m", "l", "xl"] as const;
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function KbdSizesExample() {
   return (
-    <div className={styles.sizeRow}>
-      {sizes.map((size) => (
-        <div key={size} className={styles.sizeCell}>
-          <span className={styles.chord}>
-            <Kbd.Root size={size}>Ctrl</Kbd.Root>
-            <Kbd.Root size={size}>K</Kbd.Root>
-          </span>
-          <Typography.Root as="span" variant="caption" tone="muted">
+    <div>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <Kbd size={size}>Ctrl</Kbd>
+          <Typography as="span" variant="caption" tone="muted">
             {size}
-          </Typography.Root>
+          </Typography>
         </div>
       ))}
     </div>

package/src/components/label/COMPONENT.md

@@ -1,15 +1,16 @@
 # Label
 
 **Category:** inputs
+**Kind:** primitive
 
 > Field label (native `<label>`) with required and optional markers.
 
 ## When to use
-- Above a control that has no built-in `label` prop: DigitInput, ColorPicker, custom controls, or a hand-built field where you wire the ids yourself.
-- When a label needs an icon (`Label.Icon`) or an inline clarification (`Label.Sub`) next to a standalone control.
+- Above a control that has no built-in `label` prop: SegmentedControl, a custom control, or a hand-built field where you wire the ids yourself.
+- When a label needs an icon (`Label.Icon`) or an inline clarification (`Label.Description`).
 
 ## When not to use
-- Input, Textarea (and other fields with a `label` prop) → pass `label`, `required`, `optional` to the field; it renders Label itself ([Input](../input/COMPONENT.md), [Textarea](../textarea/COMPONENT.md)).
+- Input, Textarea, Select and other fields with a `label` prop → pass `label`, `required`, `optional` to the field; it renders Label itself ([Input](../input/COMPONENT.md), [Textarea](../textarea/COMPONENT.md)).
 - Help or error text under a field → use [Hint](../hint/COMPONENT.md).
 - Labels for checkboxes, radios and switches → use their own label parts ([Checkbox](../checkbox/COMPONENT.md), [Radio](../radio/COMPONENT.md), [Switch](../switch/COMPONENT.md)).
 - Section or card headings → use [Typography](../typography/COMPONENT.md).
@@ -22,32 +23,36 @@ import { Label } from "prime-ui-kit";
 
 ## Anatomy
 ```
-Label.Root        <label>: text, then the required `*` or the optional marker
-├─ Label.Icon     muted leading icon slot (sized by the label size)
-└─ Label.Sub      muted inline clarification (units, context)
+Label.Root            <label>: text, then the required `*` or the optional marker
+├─ Label.Icon         muted leading icon slot (sized by the label size, aria-hidden)
+└─ Label.Description  muted inline clarification (units, context)
 ```
 
 ## API
 
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 ### Label.Root
-`forwardRef` to `HTMLLabelElement`. + native `<label>` props except `size` (`htmlFor`, `id`, `className`, …).
+`ref` → `HTMLLabelElement`. The native `<label>`: text, then the required `*` or the optional marker; provides its size to the icons inside.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Size of the paired field: xs/s 12/16 · m 13/20 · l/xl 14/20, weight 500. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Size of the paired field: xs/s 12/16 · m 13/20 · l/xl 14/20, weight 500. Without it the tier of its host, else `m`. |
 | `required` | `boolean` | — | Appends a red `*` (`aria-hidden`). Put native `required` on the control itself. |
 | `optional` | `boolean` | — | Appends the muted optional marker (`labels.optional`). |
-| `disabled` | `boolean` | — | Disabled text color for the text and markers, `aria-disabled`. |
-| `labels` | `Partial<LabelLabels>` | see Accessibility | Built-in strings. |
-| `htmlFor` | `string` | — | Id of the associated native control. For custom controls give the label an `id` and use `aria-labelledby` on the control. |
+| `disabled` | `boolean` | — | Disabled color for the text and the markers, `aria-disabled`. |
+| `labels` | `Partial<LabelLabels>` | — | Built-in strings, see Labels. |
+| `htmlFor` | `string` | — | Id of a native control. For a custom control give the label an `id` and set `aria-labelledby` on the control. |
+| `…rest` | `Omit<LabelHTMLAttributes<HTMLLabelElement>, "size">` | — | `id`, `className` and the other label attributes. |
 
 ### Label.Icon
-+ native `<span>` props. Muted, non-shrinking icon slot; provides the label size to the icon through the control-size context.
+`ref` → `HTMLSpanElement`. A muted, non-shrinking icon slot (`aria-hidden`) before the text; kit icons take the label size. Native `<span>` props.
 
-### Label.Sub
-+ native `<span>` props. Regular weight, muted text in the same line.
+### Label.Description
+`ref` → `HTMLSpanElement`. Regular-weight muted text in the same line (units, context); part of the accessible name. Native `<span>` props.
 
 ## Variants
+Label has no `variant` or `tone`.
 
 ### size
 | Value | Looks like | Use when | Default |
@@ -60,15 +65,15 @@ Label.Root        <label>: text, then the required `*` or the optional marker
 
 **Sizes:** always the size of the field below. `xs`/`s` and `l`/`xl` share the type size; the difference is in the field height.
 
-### Markers
-| Flag | Looks like | Use when | Default |
+### Flags
+| Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `required` | Red `*` right after the text | Most fields are optional — mark the required ones | — |
 | `optional` | Muted regular «необязательно» right after the text | Most fields are required — mark the optional ones | — |
-| `disabled` | Text, `*`, marker, sub and icon in disabled color | The paired control is disabled | — |
+| `disabled` | Text, `*`, marker, description and icon in disabled color | The paired control is disabled | — |
 
 **Combinations**
-- Recommended: mark the minority of fields in a form; `Label.Sub` for units ("₽, без НДС").
+- Recommended: mark the minority of fields in a form; `Label.Description` for units («₽, без НДС»).
 - Pointless: `required` and `optional` together.
 - Forbidden: `required` without native `required` (or `aria-required`) on the control — the asterisk is decorative only.
 
@@ -85,41 +90,37 @@ The label has no hover or focus state; clicking it focuses the control bound wit
 - Inline-flex, wraps long text (`overflow-wrap: anywhere`); markers are separated by `--prime-space-1`.
 
 ## Accessibility
-- Bind with `htmlFor` to a native control, or set `id` on the label and `aria-labelledby` on a custom control (Select trigger, DigitInput group).
+
+### Keyboard
+No keyboard interaction.
+
+### ARIA
+- Bind with `htmlFor` to a native control, or set `id` on the label and `aria-labelledby` on a custom control (SegmentedControl, DigitInput group).
 - The `*` is `aria-hidden`; requiredness must come from the control (`required`).
-- The optional marker is visible text and is part of the accessible name.
+- The optional marker and `Label.Description` are visible text and part of the accessible name; `Label.Icon` is `aria-hidden`.
 
-| `labels` key | Default | Used for |
-|---|---|---|
-| `optional` | `"необязательно"` | Marker after the text when `optional` |
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-## Examples
-| File | Scenario | When to use this pattern |
+| Key | Default | Used for |
 |---|---|---|
-| [sizes.tsx](examples/sizes.tsx) | `xs`…`xl` with `required` | Matching the field size |
-| [markers.tsx](examples/markers.tsx) | `required`, `optional`, custom `labels.optional`, `Label.Sub` | Marking fields in a form |
-| [states.tsx](examples/states.tsx) | Default and `disabled` with markers | Next to a disabled control |
-| [with-icon.tsx](examples/with-icon.tsx) | `Label.Icon` on `m` and `l` | Icon before the label text |
-| [in-form.tsx](examples/in-form.tsx) | Input built-in labels next to `Label.Root` over a Select (`aria-labelledby`) | Labelling controls without a `label` prop |
+| `optional` | `"необязательно"` | Marker after the text when `optional`. |
 
-```tsx
-import { Label } from "prime-ui-kit";
-
-export function RoleLabel() {
-  return (
-    <Label.Root id="role-label" required>
-      Роль
-    </Label.Root>
-  );
-}
-```
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A standalone label above a control without its own `label`, linked through `aria-labelledby`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size; the label takes the size of the field below it — `size`. |
+| [states.tsx](examples/states.tsx) | A default label next to a disabled one; the markers dim with the text — `disabled`. |
+| [with-icon.tsx](examples/with-icon.tsx) | A muted icon before the text, sized by the label — `Label.Icon`. |
+| [structure.tsx](examples/structure.tsx) | The required asterisk, the optional marker and an inline clarification — `required`, `optional`, `Label.Description`. |
 
 ## Mistakes
 - `<Label.Root>` above an Input → use `label` on `Input.Root` instead.
 - `required` on the label only → add native `required` on the control.
-- `htmlFor` pointing at a Select trigger or a fieldset → use `id` + `aria-labelledby`.
+- `htmlFor` pointing at a custom control or a fieldset → use `id` + `aria-labelledby`.
 - Label size different from the field size → use the same `size`.
 
 ## Related
-- [Hint](../hint/COMPONENT.md) — text under the field.
-- [Input](../input/COMPONENT.md), [Textarea](../textarea/COMPONENT.md), [Select](../select/COMPONENT.md), [DigitInput](../digit-input/COMPONENT.md).
+- **Built from:** —
+- **See also:** [Hint](../hint/COMPONENT.md) — text under the field; [Input](../input/COMPONENT.md), [Textarea](../textarea/COMPONENT.md), [Select](../select/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

package/src/components/label/examples/examples.module.css

@@ -1,37 +1,16 @@
-/* Layout helpers for the Label examples. Semantic tokens only. */
+/* Layout of the Label scenarios: semantic tokens only. */
 
-.sizes {
+/* overview.tsx: label → control gap of the m tier, like a field's own label. */
+.field {
   display: flex;
-  flex-wrap: wrap;
-  align-items: flex-end;
-  justify-content: center;
-  gap: var(--prime-space-8);
+  flex-direction: column;
+  align-items: flex-start;
+  gap: var(--prime-control-m-label-gap);
 }
 
-.sizeCell {
+/* structure.tsx: one label per row, its caption under it. */
+.structure {
   display: flex;
   flex-direction: column;
-  align-items: center;
-  gap: var(--prime-space-2);
-}
-
-.list {
-  display: grid;
-  justify-items: start;
   gap: var(--prime-space-4);
 }
-
-.form {
-  display: grid;
-  gap: var(--prime-space-5);
-  width: 100%;
-  max-width: var(--prime-modal-width-s);
-  padding: var(--prime-card-padding-m);
-  border-radius: var(--prime-card-radius);
-  background: var(--prime-color-card-bg);
-}
-
-.field {
-  display: grid;
-  gap: var(--prime-control-m-label-gap);
-}

package/src/components/label/examples/overview.tsx

@@ -0,0 +1,17 @@
+/** A standalone label above a control without its own `label`, linked through `aria-labelledby`. */
+import { Label, SegmentedControl } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function LabelOverviewExample() {
+  return (
+    <div className={styles.field}>
+      <Label.Root id="report-period-label">Период отчёта</Label.Root>
+      <SegmentedControl.Root defaultValue="week" aria-labelledby="report-period-label">
+        <SegmentedControl.Item value="day">День</SegmentedControl.Item>
+        <SegmentedControl.Item value="week">Неделя</SegmentedControl.Item>
+        <SegmentedControl.Item value="month">Месяц</SegmentedControl.Item>
+      </SegmentedControl.Root>
+    </div>
+  );
+}

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

@@ -1,21 +1,17 @@
-/** Label sizes match the paired field: xs/s 12/16 · m 13/20 · l/xl 14/20. Always use the size of the field below. */
-import { type ControlSize, Label, Typography } from "prime-ui-kit";
+/** Every size; the label takes the size of the field below it — `size`. */
+import { Label, Typography } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
-const sizes: ControlSize[] = ["xs", "s", "m", "l", "xl"];
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function LabelSizesExample() {
   return (
-    <div className={styles.sizes}>
-      {sizes.map((size) => (
-        <div key={size} className={styles.sizeCell}>
-          <Label.Root size={size} required>
-            Email
-          </Label.Root>
-          <Typography.Root as="span" variant="caption" tone="muted">
+    <div>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <Label.Root size={size}>Рабочая почта</Label.Root>
+          <Typography as="span" variant="caption" tone="muted">
             {size}
-          </Typography.Root>
+          </Typography>
         </div>
       ))}
     </div>

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

@@ -1,20 +1,23 @@
-/** The label itself is not interactive; `disabled` dims the text together with the asterisk and the optional marker. Use it next to a disabled control. */
-import { Label } from "prime-ui-kit";
-
-import styles from "./examples.module.css";
+/** A default label next to a disabled one; the markers dim with the text — `disabled`. */
+import { Label, Typography } from "prime-ui-kit";
 
 export default function LabelStatesExample() {
   return (
-    <div className={styles.list}>
-      <Label.Root htmlFor="label-st-1" required>
-        Название профиля
-      </Label.Root>
-      <Label.Root htmlFor="label-st-2" disabled required>
-        Название профиля
-      </Label.Root>
-      <Label.Root htmlFor="label-st-3" disabled optional>
-        Описание
-      </Label.Root>
+    <div>
+      <div>
+        <Label.Root required>Название проекта</Label.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          default
+        </Typography>
+      </div>
+      <div>
+        <Label.Root required disabled>
+          Название проекта
+        </Label.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          disabled
+        </Typography>
+      </div>
     </div>
   );
 }

package/src/components/label/examples/structure.tsx

@@ -0,0 +1,32 @@
+/** The required asterisk, the optional marker and an inline clarification — `required`, `optional`, `Label.Description`. */
+import { Label, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function LabelStructureExample() {
+  return (
+    <div className={styles.structure}>
+      <div className={styles.field}>
+        <Label.Root required>ИНН</Label.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          required
+        </Typography>
+      </div>
+      <div className={styles.field}>
+        <Label.Root optional>КПП</Label.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          optional
+        </Typography>
+      </div>
+      <div className={styles.field}>
+        <Label.Root>
+          Бюджет
+          <Label.Description>₽, без НДС</Label.Description>
+        </Label.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          Label.Description
+        </Typography>
+      </div>
+    </div>
+  );
+}

package/src/components/label/examples/with-icon.tsx

@@ -1,23 +1,31 @@
-/** `Label.Icon` puts a muted icon before the text, sized by the label size. Use it when an icon helps scan a long form. */
-import { Icon, Label } from "prime-ui-kit";
-
-import styles from "./examples.module.css";
+/** A muted icon before the text, sized by the label — `Label.Icon`. */
+import { Icon, Label, Typography } from "prime-ui-kit";
 
 export default function LabelWithIconExample() {
   return (
-    <div className={styles.list}>
-      <Label.Root htmlFor="label-icon-email" required>
-        <Label.Icon>
-          <Icon name="field.email" />
-        </Label.Icon>
-        Рабочий email
-      </Label.Root>
-      <Label.Root htmlFor="label-icon-lock" size="l">
-        <Label.Icon>
-          <Icon name="status.locked" />
-        </Label.Icon>
-        Пароль
-      </Label.Root>
+    <div>
+      <div>
+        <Label.Root>
+          <Label.Icon>
+            <Icon name="field.email" />
+          </Label.Icon>
+          Рабочая почта
+        </Label.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          m
+        </Typography>
+      </div>
+      <div>
+        <Label.Root size="l">
+          <Label.Icon>
+            <Icon name="status.locked" />
+          </Label.Icon>
+          Пароль
+        </Label.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          l
+        </Typography>
+      </div>
     </div>
   );
 }

package/src/components/link-button/COMPONENT.md

@@ -1,17 +1,20 @@
 # LinkButton
 
 **Category:** actions
+**Kind:** primitive
 
 > A real link styled as a text action, sized on the control tiers.
 
 ## When to use
 - Navigation to another page or URL inside text, cards, forms and footers.
-- Secondary navigation next to a Button of the same size (“Войти по паролю” beside “Продолжить”).
+- Secondary navigation next to a Button of the same size («Войти по паролю» beside «Продолжить»).
 - Quiet service links in footers and metadata (`tone="neutral"`).
 - External links (`target="_blank"` + `rel="noopener noreferrer"`).
+- A router link with the link look (`asChild` around the router's `<Link>`).
+- An inline action inside running text that must read as a link («Отправить ещё раз», «выберите файл») — `asChild` around a `<button type="button">`.
 
 ## When not to use
-- An action without a URL (save, open a dialog) → use [Button](../button/COMPONENT.md) with `variant="ghost"`.
+- An action without a URL outside running text (save, open a dialog) → use [Button](../button/COMPONENT.md) with `variant="ghost"`.
 - A navigation item that must look like a button → use [Button](../button/COMPONENT.md) with `asChild` and an `<a>`.
 - The path to the current page → use [Breadcrumb](../breadcrumb/COMPONENT.md).
 - Long-form text styling → use [Typography](../typography/COMPONENT.md).
@@ -21,18 +24,27 @@
 import { LinkButton } from "prime-ui-kit";
 ```
 
+## Anatomy
+```
+LinkButton   <a> (without href when disabled, or the child with asChild); tone, size; size tier for nested icons
+└─ children  text and optional Icon before or after it
+```
+
 ## API
 
-### LinkButton.Root
-`forwardRef` → `HTMLAnchorElement` (the `<span>` when `disabled`). + native `<a>` props (`href`, `target`, `rel`, `download`, `onClick`, `aria-*` …). No `asChild`.
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### LinkButton
+`ref` → `HTMLAnchorElement` (the child with `asChild`). A native `<a>` styled as a text action; passes its tier to nested icons.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Text size, line height, icon size and gap; provided to nested `Icon`. |
-| `tone` | `"accent" \| "neutral"` | `"accent"` | `accent` — a regular link; `neutral` — quiet link. |
-| `disabled` | `boolean` | `false` | Renders `<span role="link" aria-disabled="true" tabIndex={-1}>` without `href`; native anchor props are not passed. |
-| `children` | `ReactNode` | — | Text and optional `Icon`s. |
-| `className` | `string` | — | Extra class on the root. |
+| `tone` | `"accent" \| "neutral"` | `"accent"` | `accent` — a regular link; `neutral` — secondary text, primary on hover, for footers and metadata. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Control tier: text 12 · 13 · 14 · 16 · 18, line height and icon size. Without it the tier of its host (a form, a panel, a hint), else `m`. |
+| `disabled` | `boolean` | `false` | Renders `<a role="link" aria-disabled="true" tabIndex={-1}>` without `href` and swallows the click; `id`, `aria-*` and the other native props stay. |
+| `asChild` | `boolean` | `false` | Merges the link look onto its single child instead of rendering `<a>`: a router link, or a `<button type="button">` for an inline action that is not navigation. `disabled` becomes `aria-disabled` and swallows the click. |
+| `children` | `ReactNode` | — | Text and optional `Icon`s before or after it; the text is the accessible name. |
+| `…rest` | `AnchorHTMLAttributes<HTMLAnchorElement>` | — | `href`, `target`, `rel`, `download`, `onClick`, `className`, `aria-*` and the other anchor attributes. |
 
 ## Variants
 
@@ -51,18 +63,20 @@ import { LinkButton } from "prime-ui-kit";
 | `l` | 16/24 text, icon 20, gap 8 | reading text (`body-l`), next to `l` controls | |
 | `xl` | 18/24 text (title-l), icon 20, gap 8 | prominent links in hero blocks | |
 
-Match the link size to the surrounding text or to the Button it sits next to.
+Match the link size to the surrounding text or to the Button it sits next to. Avoid `neutral` links inside body text (they read as plain text) and a LinkButton as the primary action of a form.
 
-**Combinations**
-- Recommended: `accent` inside text and next to actions; `neutral` + `s` for service links.
-- Avoid: `neutral` links inside body text (they read as plain text); making LinkButton the primary action of a form — use Button.
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `disabled` | `text-disabled`, no underline, `cursor: not-allowed` | a destination is temporarily unavailable | off |
+| `asChild` | the link look on the child (router link, `<button>`; button chrome removed) | router links; inline actions in text | off |
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
 | hover | pointer | hover color + underline (`text-decoration-color: currentColor`) |
 | focus-visible | keyboard | outer focus ring with `--prime-focus-offset`, radius `--prime-radius-xs` |
-| disabled | `disabled` | `<span role="link">`, `aria-disabled="true"`, `tabIndex=-1`, `data-disabled="true"`, `text-disabled` color, no underline, `cursor: not-allowed` |
+| disabled | `disabled` | `<a role="link">` without `href`, `aria-disabled="true"`, `tabIndex=-1`, `data-disabled="true"` |
 
 Root attributes: `data-size`, `data-tone`, `data-disabled` (only when disabled).
 
@@ -73,37 +87,40 @@ Root attributes: `data-size`, `data-tone`, `data-disabled` (only when disabled).
 - `max-width: 100%`; `display: inline-flex` with icon and text centered.
 
 ## Accessibility
-- A native `<a>`: Enter follows the link; it is announced as a link.
-- The disabled state is a non-focusable `span role="link"` with `aria-disabled`.
-- Icons are decorative; the text is the accessible name.
-- External links: say “новая вкладка” in the text or `aria-label`.
-- No `labels` keys.
 
-## Examples
-| File | Scenario | When to use this pattern |
-|---|---|---|
-| [sizes.tsx](examples/sizes.tsx) | Five size tiers | matching surrounding text or controls |
-| [tones.tsx](examples/tones.tsx) | `accent` vs `neutral` | regular vs quiet links |
-| [states.tsx](examples/states.tsx) | Active link; disabled in both tones | unavailable destinations |
-| [with-icon.tsx](examples/with-icon.tsx) | Leading and trailing `Icon` | hinting at the destination |
-| [composition.tsx](examples/composition.tsx) | Link in text, beside a Button, neutral footer links | sign-in and form cards |
-| [external-link.tsx](examples/external-link.tsx) | `target="_blank"` + `rel` | links leaving the app |
+### Keyboard
+| Key | Action |
+|---|---|
+| `Enter` | Follows the link (native `<a>`). |
+| `Tab` | Moves focus; a disabled link is skipped. |
 
-```tsx
-import { LinkButton } from "prime-ui-kit";
+### ARIA
+- A native `<a>`: announced as a link, named by its text.
+- The disabled state is a non-focusable `<a role="link" aria-disabled="true">` without `href`; it keeps `id` and `aria-*`.
+- With `asChild` the child gives the role and name: a router link, or a `<button>` for an action.
+- Icons are decorative; say «новая вкладка» in the text or `aria-label` for external links.
 
-export function DocsLink() {
-  return <LinkButton.Root href="/docs">Документация</LinkButton.Root>;
-}
-```
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+No `labels`.
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A link inside running text that keeps the text's size — `href`. |
+| [variants.tsx](examples/variants.tsx) | A regular link and a quiet one for footers and metadata — `tone`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier; text and icon follow the control tier, xs 12 to xl 18 — `size`. |
+| [states.tsx](examples/states.tsx) | A disabled link drops `href` and leaves the Tab order, in both tones — `disabled`. |
+| [with-icon.tsx](examples/with-icon.tsx) | An icon before or after the text; `Icon` without a size takes the link tier — `Icon`. |
+| [external-link.tsx](examples/external-link.tsx) | A link that leaves the app opens a new tab and says so in its text — `target`, `rel`. |
+| [as-child.tsx](examples/as-child.tsx) | The link look on a button for an inline action that is not navigation — `asChild`. |
 
 ## Mistakes
-- `<LinkButton.Root onClick={save}>` without `href` → use `Button.Root variant="ghost"`.
-- `disabled` link with `aria-label`/`title` expecting them to render → in the disabled state only children are rendered; put the meaning in the text.
+- `<LinkButton onClick={save}>` without `href` → an `<a>` without a URL is not a button: use `<Button.Root variant="ghost">`, or `<LinkButton asChild><button type="button">` inside running text.
 - `target="_blank"` without `rel="noopener noreferrer"` → add `rel`.
 - Wrapping a LinkButton in an `<a>` → pass `href` directly.
 
 ## Related
-- [Button](../button/COMPONENT.md)
-- [Breadcrumb](../breadcrumb/COMPONENT.md)
-- [Typography](../typography/COMPONENT.md)
+- **Built from:** —
+- **See also:** [Button](../button/COMPONENT.md), [Breadcrumb](../breadcrumb/COMPONENT.md), [Typography](../typography/COMPONENT.md)

package/src/components/link-button/examples/as-child.tsx

@@ -0,0 +1,18 @@
+/** The link look on a button for an inline action that is not navigation — `asChild`. */
+import { LinkButton, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+export default function LinkButtonAsChildExample() {
+  const [sent, setSent] = React.useState(false);
+
+  return (
+    <Typography variant="body-m" tone="secondary">
+      {sent ? "Письмо отправлено повторно." : "Не пришло письмо со счётом?"}{" "}
+      <LinkButton asChild>
+        <button type="button" onClick={() => setSent(true)}>
+          Отправить ещё раз
+        </button>
+      </LinkButton>
+    </Typography>
+  );
+}

package/src/components/link-button/examples/external-link.tsx

@@ -1,14 +1,14 @@
-/** External link with `target="_blank"` and `rel="noopener noreferrer"` passed to the native `<a>`. Use for links leaving the app; say in the text that a new tab opens. */
+/** A link that leaves the app opens a new tab and says so in its text — `target`, `rel`. */
 import { LinkButton, Typography } from "prime-ui-kit";
 
 export default function LinkButtonExternalLinkExample() {
   return (
-    <Typography.Root variant="body-m" tone="secondary">
-      Подробности в{" "}
-      <LinkButton.Root href="https://example.com/docs" target="_blank" rel="noopener noreferrer">
+    <Typography variant="body-m" tone="secondary">
+      Тарифы и лимиты описаны в{" "}
+      <LinkButton href="https://example.com/docs" target="_blank" rel="noopener noreferrer">
         документации (новая вкладка)
-      </LinkButton.Root>
+      </LinkButton>
       .
-    </Typography.Root>
+    </Typography>
   );
 }

package/src/components/link-button/examples/overview.tsx

@@ -0,0 +1,11 @@
+/** A link inside running text that keeps the text's size — `href`. */
+import { LinkButton, Typography } from "prime-ui-kit";
+
+export default function LinkButtonOverviewExample() {
+  return (
+    <Typography variant="body-m" tone="secondary">
+      Ссылка для входа отправлена на почту. Не пришло письмо?{" "}
+      <LinkButton href="#resend">Отправить ещё раз</LinkButton>
+    </Typography>
+  );
+}