@d4gger/design-system 2.7.0 → 3.0.0

package/dist/docs/{toast.md → components/toast.md}

@@ -3,13 +3,6 @@ title: Toast
 status: canonical
 category: Components
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/toast/Toast.tsx
-css_path: packages/d4gger-design-system/src/styles/components/toast.css
-props_path: packages/d4gger-design-system/src/components/toast/toast.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Toast.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/overlay.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - "@radix-ui/react-toast"
   - "@radix-ui/react-slot"
@@ -18,7 +11,7 @@ depends_on:
 
 # Toast
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -73,7 +66,7 @@ The `Toast.Viewport` slot accepts the full `ComponentPropsWithoutRef<typeof Toas
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `variant` | `'default' \| 'destructive'` | `'default'` | no | Drives `data-variant` on the root. The CSS file consumes `data-variant='destructive'` to swap the background to the error container and the text to the on-error container. | no |
+| `variant` | `'default' \| 'success' \| 'warning' \| 'destructive' \| 'info'` | `'default'` | no | Drives `data-variant` on the root. Status variants swap the background to the matching container and the text to the on-container color. | no |
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Drives `data-size` on the root. The CSS file consumes `data-size` for token-driven sizing variants. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-toast`. | no |
 
@@ -109,7 +102,7 @@ The close also accepts the full `ComponentPropsWithoutRef<typeof ToastPrimitive.
 
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
-| `data-variant` | `default`, `destructive` | `.dsx-toast[data-variant='destructive']`, `.dsx-toast-variant-destructive` | `toast.css` |
+| `data-variant` | `default`, `success`, `warning`, `destructive`, `info` | `.dsx-toast[data-variant='...']`, `.dsx-toast-variant-...` | `toast.css` |
 | `data-size` | `sm`, `md`, `lg` | `.dsx-toast[data-size='…']` | `toast.css` |
 | `data-state` (Radix) | `open`, `closed` | `.dsx-toast[data-state='open']` | `toast.css` |
 | `data-swipe-direction` (Radix) | `up`, `down`, `left`, `right` | (Radix) | `toast.css` |

package/dist/docs/{toggle-group.md → components/toggle-group.md}

@@ -3,13 +3,6 @@ title: ToggleGroup
 status: canonical
 category: Components
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/toggleGroup/ToggleGroup.tsx
-css_path: packages/d4gger-design-system/src/styles/components/toggle-group.css
-props_path: packages/d4gger-design-system/src/components/toggleGroup/toggleGroup.props.ts
-test_path: packages/d4gger-design-system/src/test/components/ToggleGroup.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/forms.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - "@radix-ui/react-toggle-group"
   - Toggle
@@ -17,7 +10,7 @@ depends_on:
 
 # ToggleGroup
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 

package/dist/docs/{toggle-tip.md → components/toggle-tip.md}

@@ -3,11 +3,6 @@ title: ToggleTip
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/toggleTip/ToggleTip.tsx
-css_path: packages/d4gger-design-system/src/styles/components/toggle-tip.css
-props_path: packages/d4gger-design-system/src/components/toggleTip/toggleTip.props.ts
-test_path: packages/d4gger-design-system/src/test/components/ToggleTip.test.tsx
-demo_path: apps/playground/app/page.tsx
 depends_on:
   - Popover (Radix `@radix-ui/react-popover`; the trigger, portal, content, and arrow are Radix Popover primitives; the open/close behavior is local to `ToggleTip`)
   - Tooltip (the trigger and content visuals share the `dsx-tooltip` aesthetic; the roster lists ToggleTip as "Popover, Tooltip" composed-from)
@@ -17,7 +12,7 @@ depends_on:
 
 # ToggleTip
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -108,7 +103,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Trigger hover text | `var(--dsx-color-primary)` | Hover glyph. |
 | Content padding | `var(--dsx-space-sm)` block, `var(--dsx-space-md)` inline | Inner gutter. |
 | Content radius | `var(--dsx-rounded-md)` | Panel corner radius. |
-| Content fill | `var(--dsx-color-surface-overlay)` | Panel surface. |
+| Content fill | `var(--dsx-color-panel-translucent)` | Panel surface. |
 | Content border | `var(--dsx-border-width-sm)` + `var(--dsx-color-outline)` | Panel edge. |
 | Content text | `var(--dsx-color-on-surface)` | Body text. |
 | Content typography | `var(--dsx-typography-body-small-*)` | Body type ramp. |
@@ -116,7 +111,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Content max-width | `280px` (raw) | Readability cap; not a token target. |
 | Content entry animation | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-out)` | Fade-in. |
 | Content entry distance | `var(--dsx-space-xs)` | Translate offset. |
-| Arrow fill | `var(--dsx-color-surface-overlay)` | Match content surface. |
+| Arrow fill | `var(--dsx-color-panel-translucent)` | Match content surface. |
 | Trigger motion | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-in-out)` | Hover transitions. |
 
 Rules:
@@ -278,13 +273,13 @@ The package does not yet publish a Penpot asset for ToggleTip. Recipe is visual
 | Trigger | text | `--dsx-color-on-surface-variant` | Color | `fills` |
 | Trigger (hover) | fill | `--dsx-effect-hover-layer` | Color | `fills` (state) |
 | Trigger (hover) | text | `--dsx-color-primary` | Color | `fills` (state) |
-| Panel | fill | `--dsx-color-surface-overlay` | Color | `fills` |
+| Panel | fill | `--dsx-color-panel-translucent` | Color | `fills` |
 | Panel | stroke | `--dsx-color-outline` | Color | `strokes` |
 | Panel | radius | `--dsx-rounded-md` | Radius | `radius` |
 | Panel | shadow | `--dsx-shadow-3` | Effect | `shadow` |
 | Panel | typography | `--dsx-typography-body-small-*` | Typography | `typography` |
 | Panel | text | `--dsx-color-on-surface` | Color | `fills` |
-| Arrow | fill | `--dsx-color-surface-overlay` | Color | `fills` |
+| Arrow | fill | `--dsx-color-panel-translucent` | Color | `fills` |
 
 ### State transformations
 

package/dist/docs/{toggle.md → components/toggle.md}

@@ -3,20 +3,13 @@ title: Toggle
 status: canonical
 category: Primitives
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/toggle/Toggle.tsx
-css_path: packages/d4gger-design-system/src/styles/components/toggle.css
-props_path: packages/d4gger-design-system/src/components/toggle/toggle.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Toggle.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/actions.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Button
 ---
 
 # Toggle
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 

package/dist/docs/{toolbar.md → components/toolbar.md}

@@ -3,13 +3,6 @@ title: Toolbar
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/toolbar/Toolbar.tsx
-css_path: packages/d4gger-design-system/src/styles/components/toolbar.css
-props_path: packages/d4gger-design-system/src/components/toolbar/toolbar.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Toolbar.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/navigation.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Button
   - Toggle
@@ -19,7 +12,7 @@ depends_on:
 
 # Toolbar
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 

package/dist/docs/{tooltip.md → components/tooltip.md}

@@ -3,19 +3,12 @@ title: Tooltip
 status: canonical
 category: Primitives
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/tooltip/Tooltip.tsx
-css_path: packages/d4gger-design-system/src/styles/components/tooltip.css
-props_path: packages/d4gger-design-system/src/components/tooltip/tooltip.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Tooltip.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/overlay.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on: []
 ---
 
 # Tooltip
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -123,7 +116,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Border radius | `var(--dsx-rounded-sm)` | Content corner roundness |
 | Padding (block) | `var(--dsx-space-xs)` | Vertical padding |
 | Padding (inline) | `var(--dsx-space-sm)` | Horizontal padding |
-| Background (default) | `var(--dsx-color-surface-overlay)` | Default content fill |
+| Background (default) | `var(--dsx-color-panel-translucent)` | Default content fill |
 | Background (primary) | `var(--dsx-color-primary)` | Primary content fill |
 | Background (error) | `var(--dsx-color-error)` | Error content fill |
 | Color (default) | `var(--dsx-color-on-surface)` | Default label color |
@@ -271,7 +264,7 @@ The package does not yet publish a Penpot asset for Tooltip. Recipe is visual re
 | Content | border radius | `--dsx-rounded-sm` | Radius | `border-radius` |
 | Content | padding (block) | `--dsx-space-xs` | Spacing | `padding-top` `padding-bottom` |
 | Content | padding (inline) | `--dsx-space-sm` | Spacing | `padding-left` `padding-right` |
-| Content (default) | background | `--dsx-color-surface-overlay` | Color | `fills` |
+| Content (default) | background | `--dsx-color-panel-translucent` | Color | `fills` |
 | Content (default) | color | `--dsx-color-on-surface` | Color | `text-color` |
 | Content (primary) | background | `--dsx-color-primary` | Color | `fills` (state) |
 | Content (primary) | color | `--dsx-color-on-primary` | Color | `text-color` (state) |
@@ -285,7 +278,7 @@ The package does not yet publish a Penpot asset for Tooltip. Recipe is visual re
 
 | State | Content fill | Content color | Shadow |
 |---|---|---|---|
-| `default` | `--dsx-color-surface-overlay` | `--dsx-color-on-surface` | `--dsx-shadow-elevation-2` |
+| `default` | `--dsx-color-panel-translucent` | `--dsx-color-on-surface` | `--dsx-shadow-elevation-2` |
 | `primary` | `--dsx-color-primary` | `--dsx-color-on-primary` | `--dsx-shadow-elevation-2` |
 | `error` | `--dsx-color-error` | `--dsx-color-on-error` | `--dsx-shadow-elevation-2` |
 

package/dist/docs/{tree-view.md → components/tree-view.md}

@@ -3,11 +3,6 @@ title: TreeView
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/treeView/TreeView.tsx
-css_path: packages/d4gger-design-system/src/styles/components/tree-view.css
-props_path: packages/d4gger-design-system/src/components/treeView/treeView.props.ts
-test_path: packages/d4gger-design-system/src/test/components/TreeView.test.tsx
-demo_path: apps/playground/app/page.tsx
 depends_on:
   - Collapsible (Radix `@radix-ui/react-collapsible`; the roster lists `Collapsible` as the composed-from engine; the current runtime does not import Collapsible, see Anomalies)
   - Icon (lucide-react `ChevronRight`, `ChevronDown`, `File`)
@@ -16,7 +11,7 @@ depends_on:
 
 # TreeView
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 

package/dist/docs/{typography.md → components/typography.md}

@@ -3,22 +3,17 @@ title: Typography
 status: canonical
 category: Foundations
 archetype: primitive
-package_path: packages/d4gger-design-system/src/foundations/Typography.tsx
-test_path: packages/d4gger-design-system/src/test/foundations/Typography.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/typography.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Shared
 ---
 
 # Typography
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
-The foundation-level polymorphic `Text` and `Heading` exports that read their tone color from a CSS custom property (`--dsx-text-color` and `--dsx-heading-color`) and bind it to a `TextTone` token. Exposed as `FoundationText` and `FoundationHeading` to avoid clashing with the app-level `Text` and `Heading` components that ship from `src/components/`.
+The foundation-level polymorphic `Text` and `Heading` exports that apply the bilingual Science Gothic role presets, read their tone color from a CSS custom property (`--dsx-text-color` and `--dsx-heading-color`), and bind it to a `TextTone` token. Exposed as `FoundationText` and `FoundationHeading` to avoid clashing with the app-level `Text` and `Heading` components that ship from `src/components/`.
 
 ## Anatomy & slots
 
@@ -34,7 +29,7 @@ No slots: flat exports. Each component renders a single host element (default `s
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `variant` | `'body-large' \| 'body-medium' \| 'label-large' \| 'label-medium' \| 'label-small'` | `'body-medium'` | no | Typography ramp variant. Writes the `dsx-text--{variant}` modifier class. | no |
+| `variant` | `'body-large' \| 'body-medium' \| 'body-small' \| 'label-large' \| 'label-medium' \| 'label-small'` | `'body-medium'` | no | Typography ramp variant. Writes the `dsx-text--{variant}` modifier class. | no |
 | `tone` | `'default' \| 'muted' \| 'primary' \| 'secondary' \| 'success' \| 'error'` | `'default'` | no | Tone color; resolves to a `var(--dsx-color-*)` token and is written to the `--dsx-text-color` CSS variable. `'default'` writes no variable. | no |
 | `truncate` | `boolean` | `false` | no | When `true`, applies the `dsx-text--truncate` class (single-line ellipsis). | no |
 | `asChild` | `boolean` | `false` | no | Renders the host through `Slot` from `components/slot/Slot`; consumer supplies the host element. | no |
@@ -70,9 +65,10 @@ Rules that apply to this row:
 
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
-| (class) | `body-large`, `body-medium`, `label-large`, `label-medium`, `label-small` | `dsx-text--{variant}` | `text.css` |
+| (class) | `body-large`, `body-medium`, `body-small`, `label-large`, `label-medium`, `label-small` | `dsx-text--{variant}` | `text.css` |
 | (class) | `display-large`, `display-medium`, `headline-large`, `headline-medium` | `dsx-heading--{variant}` | `heading.css` |
 | (class) | `true` (when `truncate`) | `dsx-text--truncate` | `text.css` |
+| (class, legacy) | `muted`, `inverse` | `dsx-text--muted`, `dsx-text--inverse`, `dsx-heading--muted`, `dsx-heading--inverse` | `text.css`, `heading.css` |
 
 **Inline CSS variables (per instance):**
 
@@ -85,7 +81,8 @@ Rules that apply to this row:
 
 **Responsive behavior:**
 
-- The component does not write `@media` rules. The foundation `Text` and `Heading` do not support responsive prop values; app-level `Text` and `Heading` (`src/components/text/Text.tsx` and `src/components/heading/Heading.tsx`) carry the responsive `size` prop.
+- The component does not write `@media` rules. The foundation `Text` and `Heading` exports do not support responsive prop values; the responsive `dsx-r-*-size` classes and the `data-high-contrast` rules that live in the same `text.css` / `heading.css` files belong to the app-level `Text` and `Heading` contract (`src/components/text/Text.tsx` and `src/components/heading/Heading.tsx`, which carry the responsive `size` prop).
+- The legacy `dsx-text--muted`, `dsx-text--inverse`, `dsx-heading--muted`, and `dsx-heading--inverse` classes remain in `text.css` / `heading.css` for backward compatibility. They are not written by the foundation `tone` prop, which carries tone through the `--dsx-text-color` / `--dsx-heading-color` CSS variables instead; prefer the `tone` prop for new code.
 
 **Reduced motion:**
 
@@ -100,11 +97,12 @@ Every CSS value the component paints is a `var(--dsx-*)` token, routed through t
 | Color (text, default) | `var(--dsx-color-on-surface)` | Default text fill. |
 | Color (heading, default) | `var(--dsx-color-on-surface)` | Default heading fill. |
 | Color (tone variants) | `var(--dsx-color-on-surface-variant)`, `var(--dsx-color-primary)`, `var(--dsx-color-secondary)`, `var(--dsx-color-success)`, `var(--dsx-color-error)` | Token-backed tones. |
-| Font family, size, weight, line height, letter spacing, text transform, text decoration | `var(--dsx-typography-*-*)` token family | Typography ramp. |
+| Font family, size, weight, line height, letter spacing, variable-axis settings, text transform, text decoration | `var(--dsx-typography-*-*)` token family | Science Gothic typography ramp. |
 
 Rules:
 
 - Tokens come from `DESIGN.md` and the generated `tokens.css`. The variant classes are the only modifiers; there are no raw values in the CSS files.
+- Each role consumes its generated `font-variation-settings` token. Display and headline roles add controlled width and contrast; body roles remain neutral; label roles narrow slightly. Fallback fonts ignore unsupported axes.
 - The tone color is written to `--dsx-text-color` / `--dsx-heading-color` and consumed by the corresponding CSS files. The variable is what carries the tone; the `tone` prop is not written as a class.
 
 ## Motion contract

package/dist/docs/{visually-hidden.md → components/visually-hidden.md}

@@ -3,19 +3,13 @@ title: VisuallyHidden
 status: canonical
 category: Primitives
 archetype: radix-wrapper
-package_path: packages/d4gger-design-system/src/components/visuallyHidden/VisuallyHidden.tsx
-props_path: packages/d4gger-design-system/src/components/visuallyHidden/visuallyHidden.props.ts
-test_path: packages/d4gger-design-system/src/test/components/VisuallyHidden.test.tsx
 note: VisuallyHidden is a JS-only export. The package ships no per-component CSS file for it; the Radix primitive owns the hidden-state styling.
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/utility.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on: []
 ---
 
 # VisuallyHidden
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 

package/dist/docs/consumer-guide.md

@@ -2,7 +2,8 @@
 
 This guide describes the supported package boundary for application teams. The
 individual component specifications in this directory contain complete prop
-tables and examples and ship under `dist/docs`.
+tables and examples. They remain repository documentation rather than installed
+npm-package files.
 
 Looking for theme-specific patterns (mode, accent, density, scaling, SSR)?
 See [theme-guide.md](./theme-guide.md).
@@ -88,6 +89,24 @@ Apps that consume the package do not need to run PostCSS for DS styles.
 PostCSS is the package's build-time concern, not the consumer's runtime
 concern.
 
+### Optional-peer JavaScript entrypoints
+
+The root package and `./components` barrel contain the peer-light application
+surface. Components that require an optional adapter, or transitively compose
+one, are imported from dedicated subpaths:
+
+```tsx
+import { Dialog } from '@d4gger/design-system/dialog'
+import { SearchBar } from '@d4gger/design-system/search-bar'
+import { DatePicker } from '@d4gger/design-system/datepicker'
+```
+
+The same rule applies to `calendar`, `chart`, `combobox`, `command`,
+`config-drawer`, `drawer`, `file-upload`, `input-otp`, `phone-input`,
+`qr-code`, `resizable`, `rich-text-editor`, `sonner`, and `sortable-list`.
+Install the peer dependencies for the subpaths the application actually uses.
+Do not import internal source or `dist` files.
+
 ## Layout
 
 The layout primitives compose app shells and product pages. Pick the
@@ -372,10 +391,16 @@ derived level does not match the document outline.
 
 ### FontProvider: loading fonts at the app root
 
-`FontProvider` writes `--dsx-font-family` and `--dsx-display-font-family`
-on `document.documentElement` from the `fontFamily` and
-`displayFontFamily` props. Wrap the app in `FontProvider` at the root
-and preload the font faces through a normal `<link rel="preload">` or
+The core `styles.css` entrypoint does not make remote font requests. Prefer an
+application-native loader such as `next/font` or explicit preload links. Apps
+that want the package's hosted compatibility path may import
+`@d4gger/design-system/fonts.css` before Tailwind and other styles; that
+entrypoint loads Science Gothic and JetBrains Mono from Google Fonts.
+
+`FontProvider` writes the generated body/label and display/headline family
+properties on `document.documentElement` and `document.body` from the
+`fontFamily` and `displayFontFamily` props. Wrap the app in `FontProvider` at
+the root and preload the font faces through a normal `<link rel="preload">` or
 `next/font`.
 
 ```tsx
@@ -385,8 +410,8 @@ import { FontProvider } from '@d4gger/design-system'
 export function Root({ children }: { children: React.ReactNode }) {
   return (
     <FontProvider
-      fontFamily="var(--dsx-typography-body-medium-font-family, sans-serif)"
-      displayFontFamily="var(--dsx-typography-display-font-family, serif)"
+      fontFamily="Science Gothic, ui-sans-serif, system-ui, sans-serif"
+      displayFontFamily="Science Gothic, Arial Narrow, ui-sans-serif, system-ui, sans-serif"
       loadGoogleFonts
     >
       {children}
@@ -395,50 +420,49 @@ export function Root({ children }: { children: React.ReactNode }) {
 }
 ```
 
-The `fontFamily` default is the body-medium token reference, so the
-provider's absence does not break the typography ramp. Pass a
-free-form value when you bring your own font.
+The default families match the generated canonical tokens. The provider's
+absence does not break the typography ramp; mount it when an application needs
+an explicit family override or the hosted compatibility loader.
 
-#### Merriweather Cyrillic fallback
+#### Canonical bilingual hosted families
 
-Heading and display tokens use Fraunces with Merriweather as the
-Cyrillic serif fallback. When your product copy may include Cyrillic
-characters (Russian-language product UI, for example), pass
-`loadGoogleFonts` to inject the Google Fonts stylesheet for Merriweather
-with the `cyrillic,latin` subset.
+Science Gothic covers the Latin and Cyrillic product roles with one variable
+family. JetBrains Mono owns code and technical metadata. Pass
+`loadGoogleFonts` only when the application does not use an application-native
+loader and accepts the hosted compatibility path.
 
 ```tsx
 <FontProvider
-  fontFamily="Manrope, sans-serif"
-  displayFontFamily="Fraunces, serif"
+  fontFamily="Science Gothic, sans-serif"
+  displayFontFamily="Science Gothic, sans-serif"
   loadGoogleFonts
 >
   {children}
 </FontProvider>
 ```
 
-`loadGoogleFonts` injects a `<link rel="stylesheet">` for the Merriweather
-subset on mount and removes it on unmount. The link carries
-`id="dsx-font-provider-merriweather"`, which the provider uses to
-deduplicate when more than one provider mounts in the same document.
+`loadGoogleFonts` injects a `<link rel="stylesheet">` for Science Gothic and
+JetBrains Mono on mount and removes it on unmount. The link carries
+`id="dsx-font-provider-default-fonts"`, which the provider uses to deduplicate
+when more than one provider mounts in the same document.
 
 ### Overriding fonts through CSS custom properties
 
-The provider is the canonical writer of `--dsx-font-family`. Apps that
-want to set the value without mounting the provider can write the
-property directly. The runtime reads the value at render time, so the
-override applies immediately.
+The provider is the canonical runtime writer of the role family variables.
+Apps that do not mount it may override the generated family properties
+directly. The runtime reads them at render time, so overrides apply
+immediately.
 
 ```css
 :root {
-  --dsx-font-family: 'Manrope', sans-serif;
-  --dsx-display-font-family: 'Fraunces', 'Merriweather', serif;
+  --dsx-typography-body-medium-font-family: 'Science Gothic', sans-serif;
+  --dsx-typography-display-large-font-family: 'Science Gothic', sans-serif;
 }
 ```
 
-The order of fallback matters. The serif fallback should be Merriweather
-so Cyrillic characters in headings retain the same serif voice as the
-Latin Fraunces.
+Prefer `FontProvider` when replacing an entire body or display family because
+it coordinates every role variable and both document roots. Direct CSS is best
+reserved for controlled embedding contexts.
 
 ## Component API reference
 
@@ -906,6 +930,35 @@ closes when focus moves outside its content. Prefer the default `modal` behavior
 for forms, destructive actions, and any menu where the user should not scroll the
 page while the menu is open.
 
+## Telegram Mini App runtime integration
+
+The package runtime is host-aware without requiring a Telegram SDK dependency.
+When `ThemeProvider` is in `system` mode, it prefers
+`Telegram.WebApp.colorScheme` and listens for `themeChanged`; outside a Telegram
+WebView it uses `prefers-color-scheme`. `ThemeScript` uses the same precedence
+before hydration, so Mini Apps do not flash the host OS theme before React
+mounts. Continue to pass the same `storageKey` and defaults to both APIs.
+
+Telegram publishes its viewport and safe-area values as CSS custom properties.
+After the host calls `Telegram.WebApp.ready()`, the DS body and full-height
+Drawer use `--tg-viewport-stable-height`, falling back to `100vh` in a normal
+browser. The package also exposes host-neutral aliases for app composition:
+
+```css
+.mini-app-shell {
+  padding:
+    var(--dsx-safe-area-inset-top)
+    var(--dsx-safe-area-inset-right)
+    var(--dsx-safe-area-inset-bottom)
+    var(--dsx-safe-area-inset-left);
+}
+```
+
+The four `--dsx-safe-area-inset-*` aliases prefer Telegram's
+`--tg-safe-area-inset-*` values and fall back to the matching browser `env()`
+safe-area inset. Components do not add that padding automatically; the app shell
+owns where safe-area spacing belongs.
+
 ## Next steps
 
 - Theme system, ThemeProvider, useTheme, and the SSR guidance live in