prime-ui-kit 0.7.13 → 0.9.1

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

@@ -1,108 +1,126 @@
 # LinkButton
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
-
-## Canonical
-
-Text-style **navigation** control: **`LinkButton.Root`** only — control typography, inline-flex, underline on hover / `:focus-visible`, sizes **`s`–`xl`**. Import **`LinkButton`** from **`prime-ui-kit`**.
-
+**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 «Продолжить»).
+- 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 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).
+
+## Import
 ```tsx
 import { LinkButton } from "prime-ui-kit";
-
-<LinkButton.Root href="/settings">
-  Settings
-</LinkButton.Root>
 ```
 
-| Piece | Role |
-|--------|------|
-| `LinkButton.Root` | `<a>` with anchor props, or `<span role="link">` when `disabled` |
-
-### Playground demos
-
-Порядок и смысл совпадают с **`playground/sections/LinkButtonSection.tsx`**. Исходники с импортами **`@/`** — в **`playground/snippets/link-button/`**:
-
-| Блок в секции | Сниппет | Содержание |
-|---------------|---------|------------|
-| Размеры | [`sizes.tsx`](../../../playground/snippets/link-button/sizes.tsx) | **`size`** **`s`**–**`xl`**, подписи **LinkButton s** … **xl** |
-| Состояния | [`states.tsx`](../../../playground/snippets/link-button/states.tsx) | Активная с **`href`** и **`disabled`** (span, без перехода) |
-| Композиция с иконками | [`composition.tsx`](../../../playground/snippets/link-button/composition.tsx) | **`Icon`** слева/справа, только иконка + **`aria-label`** |
-| Внешняя ссылка | [`external-link.tsx`](../../../playground/snippets/link-button/external-link.tsx) | **`target="_blank"`** и **`rel="noopener noreferrer"`** |
-
-### Примеры в `examples/`
-
-Импорт **`"prime-ui-kit"`** — для копипаста в приложение. Зеркала сниппетов (та же структура и сценарий):
-
-| Файл | Сниппет playground |
-|------|-------------------|
-| [`sizes.tsx`](examples/sizes.tsx) | [`sizes.tsx`](../../../playground/snippets/link-button/sizes.tsx) |
-| [`disabled.tsx`](examples/disabled.tsx) | [`states.tsx`](../../../playground/snippets/link-button/states.tsx) |
-| [`composition.tsx`](examples/composition.tsx) | [`composition.tsx`](../../../playground/snippets/link-button/composition.tsx) |
-| [`external.tsx`](examples/external.tsx) | [`external-link.tsx`](../../../playground/snippets/link-button/external-link.tsx) |
-
-Дополнительные сценарии (отдельного фрейма в playground нет):
-
-| Файл | Сценарий |
-|------|----------|
-| [`inline-text-link.tsx`](examples/inline-text-link.tsx) | Встроенная ссылка в абзаце, **`size="m"`** |
-| [`footer-legal.tsx`](examples/footer-legal.tsx) | Плотный ряд legal, **`size="s"`** |
-| [`navigation-cluster.tsx`](examples/navigation-cluster.tsx) | Горизонтальная навигация с разделителями |
-
-## Extended
-
-### About
-
-- **Use** for in-app routes and sections when the UI should read as a **link**, not a filled button.
-- **Use** inline in copy (help, legal, helper text) where a compact or scaled text link fits the layout; smaller tiers often use **`size="s"`** in footers and dense chrome.
-- **Use** when nested icons should follow **control** size tokens — **`size`** sets **`ControlSizeProvider`** for children.
-- **Do not use** for actions that do not navigate (submit, toggle, open dialogs); use **Button** or another control.
-- **Do not use** expecting **`asChild`** or polymorphic roots; you cannot attach these styles to a child router **`Link`** via one prop.
-- **Do not use** **`disabled`** to mean “still in tab order with full link semantics”; disabled mode removes focus and drops anchor attributes (see Rules).
-
-### Composition
-
-- **`LinkButton`** — namespace object with **`LinkButton.Root`** only.
-- **`LinkButton.Root`** — when **`disabled`** is false (default), renders **`<a>`** with anchor attributes from props and wraps **`children`** in **`ControlSizeProvider`** for **`size`**.
-- When **`disabled`** is true, renders **`<span role="link">`** with **`aria-disabled="true"`**, **`tabIndex={-1}`**, and the same size context — no **`href`** or other spread anchor props on the DOM node.
-
-### Rules
-
-- **`size`** defaults to **`m`**; valid values are **`"s"`**, **`"m"`**, **`"l"`**, **`"xl"`** (control token tier).
-- With **`disabled={true}`**, anchor props (including **`href`**, **`target`**, **`onClick`**) are **not** applied — the root is a **`span`**; do not rely on them for accessibility or behavior in that mode.
-- Active link: native **`<a>`** with your **`href`**; keyboard **Enter** activates like a normal link.
-- Disabled presentation: **`role="link"`**, **`aria-disabled="true"`**, **`tabIndex={-1}`** — not in tab order by default; avoid if the item should remain focusable as a link.
-- For **icon-only** links, provide a name (**`aria-label`** or visible text).
-- For **`target="_blank"`**, set **`rel="noopener noreferrer"`** (and warn in UI if policy requires it).
-- There is no loading or error variant; for async work without navigation, prefer **Button** (or another pattern).
-- One visual style only (no **`variant`**); hierarchy comes from **`size`** and surrounding layout. No built-in **`fullWidth`** — use layout or **`className`** on the root if you need block-level stretch.
-- **`ref`** is forwarded to the DOM root (**`<a>`** or the disabled **`<span>`**); the public ref type is **`HTMLAnchorElement`** even though the disabled node is a **`span`**.
-
-### API
-
-#### LinkButton.Root
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Control height / type scale; size context for nested icons via `ControlSizeProvider`. |
-| disabled | `boolean` | `false` | No | Renders `span` with `role="link"` instead of `a`; no navigation. |
-| children | `React.ReactNode` | — | No | Link content (text, icons, etc.). |
-| className | `string` | — | No | Additional class on the root element. |
-| href | `string` | — | No | Navigation target on the active `<a>`; ignored when `disabled` (no `href` on the span). |
-| …anchorProps | `React.AnchorHTMLAttributes<HTMLAnchorElement>` | — | No | Other anchor attributes forwarded to `<a>` only when `disabled` is false (`target`, `rel`, `download`, `onClick`, `aria-*`, `tabIndex`, etc.); `ref` targets `<a>` or the disabled `<span>`. |
-
-### Related
-
-- [Button](../button/COMPONENT.md) — actions, forms, loading/disabled without link semantics.
-- [Breadcrumb](../breadcrumb/COMPONENT.md) — trail navigation; items may use `LinkButton` internally.
-- [Typography](../typography/COMPONENT.md) — body text and inline links without control padding; `LinkButton` matches control alignment and scale.
-
-## LLM note
+## 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
+```
 
-- **Import:** `import { LinkButton } from "prime-ui-kit"` — render **`LinkButton.Root`**; there is no flat **`LinkButton`** element export.
-- **Semantics:** Prefer **`LinkButton`** over **`Button`** when the primary affordance is **navigation** (URL change), not a command.
-- **`disabled`:** Forces **`span`** + **`aria-disabled`**; **`href` / `onClick` / `target`** from props are **ignored** — do not pass them expecting behavior.
-- **External / new tab:** Always pair **`target="_blank"`** with **`rel="noopener noreferrer"`**.
-- **Router:** No **`asChild`** — wrap router **`Link`** by styling it separately or use plain **`<a href>`** from the kit; do not invent a polymorphic API.
-- **Density:** Footer and legal rows → often **`size="s"`**; primary in-sentence link in body copy → usually **`m`** unless the surrounding control tier dictates otherwise.
-- **Icons:** Children can include **`Icon`**; size context flows from **`LinkButton.Root`** — keep icon tier consistent with **`size`** on the root.
-- **Verification:** Таблицы **Playground demos** и **Примеры в `examples/`** выше; исходники сниппетов — `playground/snippets/link-button/*.tsx`.
+## API
+
+<!-- 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 |
+|---|---|---|---|
+| `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
+
+### tone
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `accent` | accent text, medium weight; on hover `accent-hover` and an underline appears | regular links in text, forms and cards | yes |
+| `neutral` | secondary text; on hover primary text + underline | footers, metadata, dense service navigation | |
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 12/16 text, icon 14, gap 4 | captions, table meta | |
+| `s` | 13/20 text, icon 16, gap 4 | footers, secondary text | |
+| `m` | 14/20 text, icon 16, gap 4 | default UI text, next to `m` controls | yes |
+| `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. Avoid `neutral` links inside body text (they read as plain text) and a LinkButton as the primary action of a form.
+
+### 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` | `<a role="link">` without `href`, `aria-disabled="true"`, `tabIndex=-1`, `data-disabled="true"` |
+
+Root attributes: `data-size`, `data-tone`, `data-disabled` (only when disabled).
+
+## Layout & spacing
+- Inline in text: put a space before it (`{" "}`) and keep the text's size.
+- Next to a Button: same `size`, `justify-content: space-between` or `gap: var(--prime-space-3)`.
+- Footer link rows: `gap: var(--prime-space-2) var(--prime-space-4)`, wrap allowed.
+- `max-width: 100%`; `display: inline-flex` with icon and text centered.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Enter` | Follows the link (native `<a>`). |
+| `Tab` | Moves focus; a disabled link is skipped. |
+
+### 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.
+
+### 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 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
+- **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

@@ -0,0 +1,14 @@
+/** 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 variant="body-m" tone="secondary">
+      Тарифы и лимиты описаны в{" "}
+      <LinkButton href="https://example.com/docs" target="_blank" rel="noopener noreferrer">
+        документации (новая вкладка)
+      </LinkButton>
+      .
+    </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>
+  );
+}

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

@@ -1,21 +1,21 @@
-import { LinkButton } from "prime-ui-kit";
+/** Every size tier; text and icon follow the control tier, xs 12 to xl 18 — `size`. */
+import { LinkButton, Typography } from "prime-ui-kit";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
-/** `size` ladder `s`–`xl` — mirrors [`playground/snippets/link-button/sizes.tsx`](../../../../playground/snippets/link-button/sizes.tsx). */
 export default function LinkButtonSizesExample() {
   return (
-    <>
-      <LinkButton.Root href="#" size="s">
-        LinkButton s
-      </LinkButton.Root>
-      <LinkButton.Root href="#" size="m">
-        LinkButton m
-      </LinkButton.Root>
-      <LinkButton.Root href="#" size="l">
-        LinkButton l
-      </LinkButton.Root>
-      <LinkButton.Root href="#" size="xl">
-        LinkButton xl
-      </LinkButton.Root>
-    </>
+    <div>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <LinkButton href="#details" size={size}>
+            Подробнее
+          </LinkButton>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+        </div>
+      ))}
+    </div>
   );
 }

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

@@ -0,0 +1,31 @@
+/** A disabled link drops `href` and leaves the Tab order, in both tones — `disabled`. */
+import { LinkButton, Typography } from "prime-ui-kit";
+
+export default function LinkButtonStatesExample() {
+  return (
+    <div>
+      <div>
+        <LinkButton href="#export">Скачать выгрузку</LinkButton>
+        <Typography as="span" variant="caption" tone="muted">
+          default
+        </Typography>
+      </div>
+      <div>
+        <LinkButton href="#export" disabled>
+          Скачать выгрузку
+        </LinkButton>
+        <Typography as="span" variant="caption" tone="muted">
+          disabled
+        </Typography>
+      </div>
+      <div>
+        <LinkButton href="#export" tone="neutral" disabled>
+          Скачать выгрузку
+        </LinkButton>
+        <Typography as="span" variant="caption" tone="muted">
+          neutral · disabled
+        </Typography>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,21 @@
+/** A regular link and a quiet one for footers and metadata — `tone`. */
+import { LinkButton, Typography } from "prime-ui-kit";
+
+const TONES = ["accent", "neutral"] as const;
+
+export default function LinkButtonVariantsExample() {
+  return (
+    <div>
+      {TONES.map((tone) => (
+        <div key={tone}>
+          <LinkButton href="#report" tone={tone}>
+            Открыть отчёт
+          </LinkButton>
+          <Typography as="span" variant="caption" tone="muted">
+            {tone}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/link-button/examples/with-icon.tsx

@@ -0,0 +1,27 @@
+/** An icon before or after the text; `Icon` without a size takes the link tier — `Icon`. */
+import { Icon, LinkButton, Typography } from "prime-ui-kit";
+
+export default function LinkButtonWithIconExample() {
+  return (
+    <div>
+      <div>
+        <LinkButton href="#support">
+          <Icon name="field.email" />
+          Написать в поддержку
+        </LinkButton>
+        <Typography as="span" variant="caption" tone="muted">
+          leading
+        </Typography>
+      </div>
+      <div>
+        <LinkButton href="#projects">
+          Все проекты
+          <Icon name="nav.chevronRight" />
+        </LinkButton>
+        <Typography as="span" variant="caption" tone="muted">
+          trailing
+        </Typography>
+      </div>
+    </div>
+  );
+}

package/src/components/login-form/COMPONENT.md

@@ -0,0 +1,162 @@
+# LoginForm
+
+**Category:** inputs
+**Kind:** composite
+
+> A sign-in card with a logo, title, provider buttons and a form; covers sign-in, sign-up, password reset and code confirmation.
+
+## When to use
+- A standalone sign-in, sign-up, password-reset or one-time-code screen of a product.
+- The same flow inside a [Modal](../modal/COMPONENT.md) (`flat`) when sign-in is opened over a page.
+- Any short authentication step where one card holds a header, optional provider buttons, 1–5 fields and one primary action.
+
+## When not to use
+- A settings or profile form on an app page → use [Card](../card/COMPONENT.md) `panel` with [Input](../input/COMPONENT.md) fields.
+- A long multi-step wizard → use [Stepper](../stepper/COMPONENT.md) around regular forms.
+- The app frame (sidebar, header) → [AppShell](../../layout/app-shell/COMPONENT.md); a sign-in screen has none.
+
+## Import
+```tsx
+import { LoginForm } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+LoginForm.Root                      surface: card fill, radius, shadow
+├─ LoginForm.Header
+│  ├─ LoginForm.Logo                tile with the product mark
+│  ├─ LoginForm.Title               h1
+│  └─ LoginForm.Description
+└─ LoginForm.Body
+   ├─ LoginForm.Actions             provider buttons
+   ├─ Divider.Root                  «или»
+   ├─ LoginForm.Form                <form>: Input.Root … · Button submit
+   │  └─ LoginForm.Actions          primary button + ghost back action
+   └─ LoginForm.Footer              «Нет аккаунта? <LinkButton>»
+```
+Every part is optional except `Root`, `Title` and `Form`. Fields, buttons, dividers, banners and links are the regular kit components; LoginForm owns only the layout and the rhythm.
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### LoginForm.Root
+`ref` → `HTMLDivElement`. The sign-in card: card fill, radius and shadow, the tier rhythm; provides its size to the parts. Native `<div>` props.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Tier of padding, gaps and text roles; every field and button inside without its own `size` takes it. |
+| `align` | `"start" \| "center"` | `"start"` | `start` — the Modal header layout (rounded accent tile left, title over description right); `center` — a round logo above centered text. |
+| `flat` | `boolean` | `false` | Removes the card shadow (inside a Modal or on a plain page). No border either way. |
+| `className` | `string` | — | Class on the card. |
+
+### LoginForm.Header
+`ref` → `HTMLElement`. `<header>` with the logo, title and description, laid out by Root `align`. Native props.
+
+### LoginForm.Logo
+`ref` → `HTMLDivElement`. A tile for the product mark or an icon (accent tile with `start`, round with `center`); decorative unless it has an `aria-label`. Native `<div>` props.
+
+### LoginForm.Title
+`ref` → `HTMLHeadingElement`. The heading (kit Typography, text role by the tier).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `as` | `"h1" \| "h2" \| "h3"` | `"h1"` | Heading level; `h2` when the page already has an `h1`. |
+
+### LoginForm.Description
+`ref` → `HTMLParagraphElement`. The secondary line under the title (kit Typography, secondary tone). Native `<p>` props.
+
+### LoginForm.Body
+`ref` → `HTMLDivElement`. Everything under the header: provider buttons, divider, form, footer. Native `<div>` props.
+
+### LoginForm.Form
+`ref` → `HTMLFormElement`. The `<form>`: fields, then the submit button, with the field → field gap of the tier. Native form props.
+
+### LoginForm.Actions
+`ref` → `HTMLDivElement`. A column of full-width buttons: provider buttons above the form, or the primary action with a `ghost` back action. Native `<div>` props.
+
+### LoginForm.Footer
+`ref` → `HTMLParagraphElement`. The secondary line with a `LinkButton` («Нет аккаунта? Зарегистрироваться»); follows Root `align`. Native `<p>` props.
+
+## Variants
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` / `s` | padding 16, gap 24, field gap 16, title-s / title-m | inside a Modal or a narrow popover | |
+| `m` | padding 24, gap 32, field gap 20, title-l | a regular sign-in page | yes |
+| `l` | padding 32, gap 40, field gap 20, heading-s | a standalone sign-in screen on a wide canvas | |
+| `xl` | padding 40, gap 40, field gap 24, heading-m | marketing-grade sign-in, touch-first | |
+
+**Sizes:** every field and button inside (Input, DigitInput, Checkbox, Button, LinkButton…) takes the Root `size` unless it sets its own.
+
+### align
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `start` | accent icon tile on the left, title over description to its right, left-aligned footer | product screens, sign-in over a page, inside a Modal | yes |
+| `center` | round logo, centered title, description and footer | a standalone brand-first sign-in screen | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `flat` | card fill, no shadow | inside a Modal or any other surface | `false` |
+
+**Combinations**
+- Recommended: one `size` on Root only (fields and buttons follow it); `hint` / `error` on fields for validation; a danger [Banner](../banner/COMPONENT.md) at the top of `Form` for server errors.
+- Avoid: more than one primary button; provider buttons in `solid` (they compete with the submit); a Card around LoginForm.
+
+## States
+LoginForm has no state of its own. Compose them:
+
+| State | Driven by | DOM |
+|---|---|---|
+| submitting | `loading` on the submit Button, `disabled` on the fields | `aria-busy` on the button |
+| field error | `error` / `invalid` on `Input.Root`, `error` on `DigitInput` | `aria-invalid`, the error under the field |
+| server error | `Banner.Root tone="danger" role="alert"` as the first child of `LoginForm.Form` | `role="alert"` |
+
+Root carries `data-size`, `data-align` and `data-flat`.
+
+## Layout & spacing
+- header → body `--prime-space-8` (gap on Root); provider buttons → divider → form `--prime-space-4`; field → field → submit `--prime-space-5`; submit → back action `--prime-space-3`; form → footer `--prime-space-6`.
+- Spacing is `gap` on parents; no margins between parts.
+- The card has no border and is capped at the small modal width. To center it on a page, wrap it in your own flex container on the canvas.
+- Fields inside take `--prime-color-field-bg-surface`, like in Card.
+
+## Accessibility
+
+### Keyboard
+No keyboard interaction.
+
+### ARIA
+- The title is a real heading (`h1` by default) and the form is a native `<form>`: Enter submits.
+- Give `LoginForm.Form` an `aria-label` (or `aria-labelledby` pointing to the title id) so the form is a landmark.
+- Fields use `autoComplete` (`email`, `current-password`, `new-password`, `one-time-code`) so password managers and OTP autofill work.
+- Server errors in a Banner need `role="alert"`; field errors come from the fields (`aria-invalid`, described by the error).
+
+### 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) | Sign in with a provider button, e-mail and password, a «forgot password» link and a sign-up link under a centered header — `align`, `LoginForm.Actions`, `LoginForm.Form`, `LoginForm.Footer`. |
+| [sizes.tsx](examples/sizes.tsx) | Padding, gaps and text roles of the card follow the tier; the fields and buttons take the same one — `size`. |
+| [structure.tsx](examples/structure.tsx) | The minimal form: no logo, description or footer, and no shadow for a host that already is a surface — `flat`. |
+| [register.tsx](examples/register.tsx) | Sign-up: five fields in one column, a password mismatch shown as the field error — `error`, `LoginForm.Form`. |
+| [forgot-password.tsx](examples/forgot-password.tsx) | Password reset request: one field, the primary action and a quiet way back — `LoginForm.Actions`. |
+| [reset-password.tsx](examples/reset-password.tsx) | A new password after the e-mail link: two fields and a mismatch error under the second one — `error`. |
+| [verification-code.tsx](examples/verification-code.tsx) | The second step with a one-time code: a rejected code shows its error under the cells, resend is a quiet action — `DigitInput`, `LoginForm.Actions`. |
+| [states.tsx](examples/states.tsx) | The submit cycle: the button is busy while the request runs, a failed request shows a danger Banner and marks the password — `loading`, `invalid`. |
+| [narrow.tsx](examples/narrow.tsx) | On a phone-width screen the card keeps its padding, the header wraps and the buttons stay full width. |
+
+## Mistakes
+- `LoginForm.Social` → removed; provider buttons go in `LoginForm.Actions`.
+- A placeholder instead of a field label → pass `label` to the field.
+- A Card around LoginForm → the root already is the card; use `flat` inside another surface.
+- Repeating the card `size` on every field and button → set it once on Root; fields and buttons follow it.
+
+## Related
+- **Built from:** [Typography](../typography/COMPONENT.md) (`Title`, `Description`, `Footer`)
+- **See also:** [Input](../input/COMPONENT.md), [Button](../button/COMPONENT.md), [LinkButton](../link-button/COMPONENT.md), [Divider](../divider/COMPONENT.md), [DigitInput](../digit-input/COMPONENT.md), [Banner](../banner/COMPONENT.md), [Modal](../modal/COMPONENT.md)

package/src/components/login-form/examples/examples.module.css

@@ -0,0 +1,39 @@
+/* Layout helpers for the LoginForm examples. Semantic tokens only. */
+
+/* Centers one card on the stage (the card itself is capped at the modal width). */
+.stage {
+  display: flex;
+  justify-content: center;
+  width: 100%;
+  min-width: 0;
+}
+
+/* Several cards side by side, wrapping on narrow stages. */
+.row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-start;
+  justify-content: center;
+  gap: var(--prime-space-6);
+  width: 100%;
+  min-width: 0;
+}
+
+/* A field with a link under it, aligned to the field's end edge. */
+.withLink {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: var(--prime-space-2);
+}
+
+.withLink > :first-child {
+  align-self: stretch;
+}
+
+/* narrow.tsx: a phone-width stage. */
+.narrow {
+  display: flex;
+  justify-content: center;
+  width: min(100%, calc(var(--prime-space-16) * 5));
+}

package/src/components/login-form/examples/forgot-password.tsx

@@ -0,0 +1,39 @@
+/** Password reset request: one field, the primary action and a quiet way back — `LoginForm.Actions`. */
+import { Button, Icon, Input, LoginForm } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function LoginFormForgotPasswordExample() {
+  return (
+    <div className={styles.stage}>
+      <LoginForm.Root>
+        <LoginForm.Header>
+          <LoginForm.Logo>
+            <Icon name="object.key" />
+          </LoginForm.Logo>
+          <LoginForm.Title>Сброс пароля</LoginForm.Title>
+          <LoginForm.Description>
+            Введите email от аккаунта — отправим ссылку для смены пароля
+          </LoginForm.Description>
+        </LoginForm.Header>
+        <LoginForm.Body>
+          <LoginForm.Form onSubmit={(e) => e.preventDefault()}>
+            <Input.Root label="Email" required>
+              <Input.Wrapper>
+                <Input.Field type="email" autoComplete="email" placeholder="name@company.ru" />
+              </Input.Wrapper>
+            </Input.Root>
+            <LoginForm.Actions>
+              <Button.Root type="submit" fullWidth>
+                Отправить ссылку
+              </Button.Root>
+              <Button.Root variant="ghost" tone="neutral" fullWidth>
+                Вернуться ко входу
+              </Button.Root>
+            </LoginForm.Actions>
+          </LoginForm.Form>
+        </LoginForm.Body>
+      </LoginForm.Root>
+    </div>
+  );
+}