@d4gger/design-system 2.7.0 → 3.0.1

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

package/dist/docs/theme-guide.md

@@ -22,7 +22,7 @@ persisted in `localStorage` when used through `ThemeProvider`.
 |---|---|---|---|
 | `mode` | `light` \| `dark` \| `system` | `system` | `ThemeProvider.defaultTheme` |
 | `appearance` | `light` \| `dark` \| `inherit` | `inherit` | `Theme.appearance` (one render) |
-| `accentColor` | `amber` \| `silver` \| `bronze` | `amber` | `DESIGN.md` accent identity |
+| `accentColor` | `rift` \| `warp` \| `ray` \| `astral` \| `spark` | `rift` | `DESIGN.md` accent identity |
 | `grayColor` | `auto` \| `neutral` | `auto` | Gray family |
 | `radius` | `none` \| `sm` \| `md` \| `lg` \| `full` | `md` | Border radius preset |
 | `panelBackground` | `solid` \| `translucent` | `translucent` | Panel background treatment |
@@ -55,7 +55,7 @@ function App() {
     <ThemeProvider
       defaultTheme="system"
       storageKey="dsx-theme"
-      accentColor="amber"
+      accentColor="rift"
       density="comfortable"
       grayColor="auto"
       panelBackground="translucent"
@@ -77,7 +77,7 @@ defaults rather than overwritten.
 |---|---|---|---|
 | `defaultTheme` | `'light' \| 'dark' \| 'system'` | `'system'` | Initial mode when no stored value is present. |
 | `storageKey` | `string` | (required) | The localStorage key. |
-| `accentColor` | `'amber' \| 'silver' \| 'bronze'` | `'amber'` | Initial accent when no stored value is present. |
+| `accentColor` | `'rift' \| 'warp' \| 'ray' \| 'astral' \| 'spark'` | `'rift'` | Initial accent when no stored value is present. |
 | `density` | `'comfortable' \| 'compact'` | `'comfortable'` | Initial density. |
 | `grayColor` | `'auto' \| 'neutral'` | `'auto'` | Initial gray family. |
 | `mode` | (controlled, use the `mode` prop on `Theme` instead) | n/a | `ThemeProvider` does not accept a `mode` prop. The mode is read from storage on mount and updated through `useTheme`. |
@@ -150,7 +150,7 @@ import { Theme } from '@d4gger/design-system'
 
 function Showcase() {
   return (
-    <Theme accentColor="silver" density="compact" radius="full">
+    <Theme accentColor="warp" density="compact" radius="full">
       <Card>
         <Card.Content>Scoped theme for this card.</Card.Content>
       </Card>
@@ -164,7 +164,7 @@ attributes to `html` and `body`. Use this for a single-page app where
 you want the document to reflect the theme without persisting it.
 
 ```tsx
-<Theme accentColor="amber" mode="dark" applyToDocument>
+<Theme accentColor="rift" mode="dark" applyToDocument>
   <Root />
 </Theme>
 ```
@@ -175,13 +175,13 @@ The `appearance` prop overrides `mode` for a single render and accepts
 accent, density, or radius locally without disturbing the appearance.
 
 ```tsx
-<Theme appearance="inherit" accentColor="bronze" radius="lg">
+<Theme appearance="inherit" accentColor="ray" radius="lg">
   <Card>...</Card>
 </Theme>
 ```
 
 `surface` toggles whether the wrapper paints a surface. With
-`surface="theme"` the wrapper paints `var(--dsx-color-surface)` and
+`surface="theme"` the wrapper paints `var(--dsx-color-background)` and
 writes `data-has-background="true"`. With `surface="transparent"` the
 wrapper is invisible and `data-has-background` is omitted.
 
@@ -193,15 +193,15 @@ consumer's element.
 
 ### Accent color
 
-Three accents carry the brand identity. `amber` is the gold-dominant
-default, `silver` is the cool secondary, and `bronze` is the warm
-tertiary. Mix them deliberately; never combine more than one accent in
-a single view.
+Five accents carry the brand identity. `rift` is the violet
+default, `warp` is the cyan-blue alternate, `ray` is the magenta
+alternate, and `astral` and `spark` round out the palette. Mix them
+deliberately; never combine more than one accent in a single view.
 
 ```tsx
-<Theme accentColor="amber">...</Theme>
-<Theme accentColor="silver">...</Theme>
-<Theme accentColor="bronze">...</Theme>
+<Theme accentColor="rift">...</Theme>
+<Theme accentColor="warp">...</Theme>
+<Theme accentColor="ray">...</Theme>
 ```
 
 ### Gray color
@@ -286,7 +286,7 @@ export function ModeToggle() {
 import { useTheme, SegmentedControl } from '@d4gger/design-system'
 import type { ThemeAccentColor } from '@d4gger/design-system'
 
-const accents: ThemeAccentColor[] = ['amber', 'silver', 'bronze']
+const accents: ThemeAccentColor[] = ['rift', 'warp', 'ray', 'astral', 'spark']
 
 export function AccentSwitch() {
   const { accentColor, setAccentColor } = useTheme()
@@ -344,7 +344,7 @@ import { Theme, Card, DataList, Badge } from '@d4gger/design-system'
 
 function PlanShowcase() {
   return (
-    <Theme accentColor="silver" radius="full" appearance="inherit">
+    <Theme accentColor="warp" radius="full" appearance="inherit">
       <Card variant="default" size="md">
         <Card.Header>
           <Card.Title>Enterprise</Card.Title>
@@ -457,7 +457,7 @@ const themeScript = `
     var root = document.documentElement;
     root.setAttribute('data-dsx-theme', resolved);
     root.setAttribute('data-dsx-density', stored.density || 'comfortable');
-    root.setAttribute('data-accent-color', stored.accentColor || 'amber');
+    root.setAttribute('data-accent-color', stored.accentColor || 'rift');
     root.setAttribute('data-gray-color', stored.grayColor || 'auto');
     root.setAttribute('data-radius', stored.radius || 'md');
     root.setAttribute('data-panel-background', stored.panelBackground || 'translucent');
@@ -509,7 +509,7 @@ function readThemeFromCookies() {
   try {
     return JSON.parse(value) as {
       mode?: 'light' | 'dark' | 'system'
-      accentColor?: 'amber' | 'silver' | 'bronze'
+      accentColor?: 'rift' | 'warp' | 'ray' | 'astral' | 'spark'
       density?: 'comfortable' | 'compact'
       radius?: 'none' | 'sm' | 'md' | 'lg' | 'full'
       panelBackground?: 'solid' | 'translucent'
@@ -524,7 +524,7 @@ function readThemeFromCookies() {
 export default function RootLayout({ children }: { children: React.ReactNode }) {
   const stored = readThemeFromCookies()
   const mode = stored?.mode ?? 'system'
-  const accent = stored?.accentColor ?? 'amber'
+  const accent = stored?.accentColor ?? 'rift'
   const density = stored?.density ?? 'comfortable'
 
   return (
@@ -583,7 +583,7 @@ const themeScript = `
     var root = document.documentElement;
     root.setAttribute('data-dsx-theme', resolved);
     root.setAttribute('data-dsx-density', stored.density || 'comfortable');
-    root.setAttribute('data-accent-color', stored.accentColor || 'amber');
+    root.setAttribute('data-accent-color', stored.accentColor || 'rift');
     root.setAttribute('data-gray-color', stored.grayColor || 'auto');
     root.setAttribute('data-radius', stored.radius || 'md');
     root.setAttribute('data-panel-background', stored.panelBackground || 'translucent');