npm - @gravity-ui/querieskit - Versions diffs - 1.2.0 → 1.3.1 - Mend

@gravity-ui/querieskit 1.2.0 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (973) hide show

package/.agents/skills/gravity-ui/references/theming.md DELETED Viewed

@@ -1,309 +0,0 @@
-# Theming — `--g-*` tokens, `ThemeProvider`, branding, custom themes
-> **Source of truth:** this is a verbatim copy of
-> [`@gravity-ui/uikit`'s `docs/theming.md`](https://github.com/gravity-ui/uikit/blob/main/docs/theming.md).
-> The current version in the installed `node_modules` may differ — for the exact
-> file matching your version, read
-> `node_modules/@gravity-ui/uikit/build/docs/guides/theming.md` (or fetch the
-> version-pinned copy at `gravity-ui.com/llms/uikit/<major>/llms.txt`).
->
-> This copy is bundled offline. If a token you need is missing or looks different
-> here, prefer the version-matched source over this snapshot.
-For the **traps** — what goes wrong when theming a Gravity UI app (partial
-overrides, brand-on-brand contrast, scoped vs nested `ThemeProvider`, the
-customization ladder) — see [`../rules/hallucination-traps.md`](../rules/hallucination-traps.md).
-That file complements this reference rather than duplicating it.
----
-# Theming, Colors & Branding
-[English](theming.md) | [Русский](theming-ru.md)
-We use and recommend CSS variables for theming.
-Everything is driven by CSS custom properties prefixed with `--g-*`. There is no runtime styling API you need to call — you set variables and components pick them up.
-```tsx
-import {ThemeProvider, Button} from '@gravity-ui/uikit';
-import '@gravity-ui/uikit/styles/fonts.css';
-import '@gravity-ui/uikit/styles/styles.css';
-export const App = () => (
-  <ThemeProvider theme="system">
-    <Button view="action">Branded button</Button>
-  </ThemeProvider>
-);
-```
-## How theming works
-All variables live on the root class `.g-root`, which `ThemeProvider` assigns to `<body>` by
-default (change the target with the `scoped` prop). Color variables additionally live on a
-per-theme class `.g-root_theme_{themeName}`, so switching the theme swaps one set of values for
-another.
-```
-.g-root                      → structural tokens (spacing, typography metrics, border radius)
-.g-root_theme_light          → color tokens for the light theme
-.g-root_theme_dark           → color tokens for the dark theme
-```
-To customize anything, you provide new values for these CSS variables — for a single theme, for
-several themes, or globally. If you support more than one theme, set color overrides **per theme**.
-## Themes
-UIKit ships 4 built-in themes:
-| Theme      | Description                          |
-| ---------- | ------------------------------------ |
-| `light`    | Default light theme                  |
-| `dark`     | Default dark theme                   |
-| `light-hc` | Light, high-contrast (accessibility) |
-| `dark-hc`  | Dark, high-contrast (accessibility)  |
-Select the theme via `ThemeProvider`:
-```tsx
-<ThemeProvider theme="dark">{...}</ThemeProvider>
-```
-The default is `"system"`, which follows the OS color-scheme preference and resolves to `light`
-or `dark`. You can control what `system` resolves to with `systemLightTheme` / `systemDarkTheme`.
-Read or switch the theme at runtime with the `useTheme` / `useThemeValue` hooks.
-## Color token layers
-Colors are organized in **two layers**. Components and app code should only ever reference the
-**semantic** layer.
-### Private tokens
-`--g-color-private-*` are the raw palette — the actual RGB values, organized by hue and by a
-numeric scale. They exist so the semantic layer has something to point at. **Do not use them
-directly in application code**; they are an implementation detail and can change.
-Hue families: `black`, `white`, `blue`, `green`, `yellow`, `orange`, `red`, `purple`,
-`cool-grey`.
-Two flavors per step:
-- `--g-color-private-black-50` — translucent (`rgba(0, 0, 0, 0.05)`), blends with what's behind it.
-- `--g-color-private-black-50-solid` — opaque (`rgb(242, 242, 242)`), the pre-flattened equivalent.
-Use `-solid` variants when a translucent color would let an underlying element bleed through
-(e.g. overlapping elements, shadows).
-### Semantic tokens
-`--g-color-{group}-{role}` describe _intent_, not a specific hue. This is the layer you consume.
-| Group                                             | Purpose                         | Examples                                                                 |
-| ------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------ |
-| `--g-color-base-*`                                | Backgrounds & fills             | `base-background`, `base-brand`, `base-generic`, `base-danger-medium`    |
-| `--g-color-text-*`                                | Text colors                     | `text-primary`, `text-secondary`, `text-hint`, `text-brand`, `text-link` |
-| `--g-color-line-*`                                | Borders, dividers, underlines   | `line-generic`, `line-brand`, `line-focus`, `line-danger`                |
-| `--g-color-sfx-*`                                 | Effects — shadows, veils, fades | `sfx-shadow`, `sfx-veil`, `sfx-fade`                                     |
-| `--g-color-infographics-*` / `--g-color-scroll-*` | Charts, scrollbars              | `infographics-axis`, `scroll-handle`                                     |
-**Meaning conventions inside a group:**
-- **Statuses** — `info` (blue), `positive` (green), `warning` (yellow), `danger` (red),
-  `utility` (purple), `misc` (cool grey), plus `brand`, `generic` and `neutral`.
-- **Intensity** — `light` → `medium` → `heavy` go from subtle background fills to strong,
-  filled surfaces. `heavy` fills are meant to carry contrasting (`*-contrast`) text on top.
-- **Interaction** — a `-hover` suffix is the hover counterpart of the base token
-  (e.g. `base-brand` / `base-brand-hover`).
-- **Text hierarchy** — `text-primary` > `text-secondary` > `text-hint` (decreasing emphasis).
-```css
-/* status background + matching text */
-.alert-danger {
-  background: var(--g-color-base-danger-light);
-  color: var(--g-color-text-danger);
-}
-```
-## Branding
-Branding is a subset of theming: override a small, curated set of variables to make UIKit look
-like your product. In most cases you only need the accent color, fonts, and border radius.
-### Accent / brand color
-The accent color is what makes an app feel branded — action buttons, active controls, links, and
-selection highlights. Override this group (per theme):
-| Variable                            | Used for                                          |
-| ----------------------------------- | ------------------------------------------------- |
-| `--g-color-base-brand`              | Brand background (action button, active controls) |
-| `--g-color-base-brand-hover`        | Hover background                                  |
-| `--g-color-base-selection`          | Lighter brand tint (List/Table row selection)     |
-| `--g-color-base-selection-hover`    | Hover of the selection tint                       |
-| `--g-color-line-brand`              | Brand lines (active tab underline)                |
-| `--g-color-text-brand`              | Brand text                                        |
-| `--g-color-text-brand-heavy`        | Brand text over a background                      |
-| `--g-color-text-brand-contrast`     | Text placed **on top of** a brand background      |
-| `--g-color-text-link`               | Links                                             |
-| `--g-color-text-link-hover`         | Hover of links                                    |
-| `--g-color-text-link-visited`       | Visited links                                     |
-| `--g-color-text-link-visited-hover` | Hover of visited links                            |
-```css
-.g-root {
-  --g-color-base-brand: rgb(117, 155, 255);
-  --g-color-base-brand-hover: rgb(99, 143, 255);
-  --g-color-base-selection: rgba(82, 130, 255, 0.05);
-  --g-color-base-selection-hover: rgba(82, 130, 255, 0.1);
-  --g-color-line-brand: rgb(117, 155, 255);
-  --g-color-text-brand: rgb(117, 155, 255);
-  --g-color-text-brand-contrast: rgb(255, 255, 255);
-  --g-color-text-link: rgb(117, 155, 255);
-  --g-color-text-link-hover: rgb(82, 130, 255);
-}
-```
-> Set these on the theme class (e.g. `.g-root_theme_light`) if the brand color should differ
-> between light and dark; use `.g-root` for values shared by all themes.
-### Typography
-Configure fonts, weights, and per-variant metrics via `--g-font-family-*` and `--g-text-*`
-variables on the root class. Full reference — variants, sizing tokens, and customization — lives
-in the [**typography guide**](typography.md).
-```css
-.g-root {
-  --g-font-family-sans: 'Inter', sans-serif;
-  --g-text-header-font-weight: 600;
-}
-```
-### Shape (border radius)
-Controls share a border-radius scale: `--g-border-radius-{size}` where size is one of
-`xs`, `s`, `m`, `l`, `xl`. Use a token, never a hard-coded `px` value.
-```css
-/* your own component, in Gravity style */
-.my-card {
-  border-radius: var(--g-border-radius-m);
-}
-```
-Individual components expose their own radius variable aligned to the same scale, so you can
-tune one component without touching the global scale — e.g. `--g-button-border-radius`,
-`--g-card-border-radius`, `--g-modal-border-radius`, `--g-popup-border-radius`,
-`--g-text-input-border-radius`, `--g-list-container-border-radius`, `--g-focus-border-radius`.
-```css
-.g-root {
-  --g-border-radius-m: 8px; /* whole scale step */
-  --g-button-border-radius: var(--g-border-radius-l); /* just buttons */
-}
-```
-## Using colors in your code
-Consume semantic tokens directly in CSS. In JS/TSX, prefer the `Text` component's `color` prop
-and component `view`/`theme` props over inline colors.
-```css
-.card {
-  background: var(--g-color-base-generic);
-  color: var(--g-color-text-primary);
-  border: 1px solid var(--g-color-line-generic);
-  border-radius: var(--g-border-radius-l);
-}
-```
-```tsx
-import {Text} from '@gravity-ui/uikit';
-<Text color="secondary">Muted caption</Text>;
-```
-Because these are theme-aware tokens, the same markup renders correctly in every theme and
-respects any brand overrides — no conditional theme logic in your components.
-## Creating a custom theme
-Define a theme from scratch, or extend one of the built-ins with the SCSS mixins:
-```scss
-@use '@gravity-ui/uikit/styles/themes';
-// Start from the light theme, then override
-.g-root_theme_custom {
-  @include themes.g-theme-light;
-  // your overrides
-  --g-color-base-brand: rgb(117, 155, 255);
-}
-```
-Available mixins: `themes.g-theme-light`, `themes.g-theme-dark`, `themes.g-theme-light-hc`,
-`themes.g-theme-dark-hc`. Then pass your theme name to the provider:
-```tsx
-<ThemeProvider theme="custom">{...}</ThemeProvider>
-```
-### Rebranding: do it completely
-> **Don't override just 2–4 tokens.** If you only set `--g-color-base-brand`, then selection,
-> focus, links and `*-contrast` colors stay on the default accent and your UI ends up
-> mismatched. Override the **full brand token set** (the [accent table](#accent--brand-color)
-> above) — and provide values for **each theme** you support (dark themes usually need a
-> brighter brand color than light).
-Practical ways to produce a complete, consistent token set:
-- **[Themer web tool](https://gravity-ui.com/themer)** — pick a couple of brand colors in the
-  browser and export a ready theme as CSS or JSON.
-- **[`@gravity-ui/uikit-themer`](https://github.com/gravity-ui/uikit-themer)** — the same
-  generator as a library, for producing themes programmatically or wiring them into a build step.
-  ```shell
-  npm install @gravity-ui/uikit-themer
-  ```
-  ```ts
-  import {generateCSS, updateBaseColor, DEFAULT_THEME} from '@gravity-ui/uikit-themer';
-  // Change a base color; private/dependent tokens are recalculated for you.
-  const theme = updateBaseColor({
-    theme: DEFAULT_THEME,
-    colorToken: 'brand',
-    value: {light: '#007AFF', dark: '#007AFF'},
-  });
-  // Emit CSS with .g-root_theme_light / .g-root_theme_dark blocks.
-  const css = generateCSS({theme, ignoreDefaultValues: true});
-  ```
-  It also exposes `generateJSON` / `parseCSS` / `parseJSON` and CSS↔JSON converters. Always use
-  `updateBaseColor` (rather than editing tokens by hand) so the private palette regenerates and
-  the theme stays internally consistent.
-- **SCSS mixins** — extend a built-in theme (above) and layer overrides on top.
-Whichever you use, **import the generated theme file _after_ `styles.css`** so it wins the
-cascade; `ThemeProvider` activates it via the theme class automatically. Keep the brand
-definition in a single theme file — don't search-and-replace `--g-*` variables across your codebase.
-### Scoped themes
-To apply a different theme to just one region (e.g. a dark toolbar in a light app), nest a
-`scoped` provider — it sets the theme class locally and updates React context for descendants
-without polluting the global root:
-```tsx
-<ThemeProvider scoped theme="dark">
-  <Toolbar />
-</ThemeProvider>
-```
-For a CSS-only region (no context update), apply the class from `getRootClassName({theme: 'dark'})`.

package/.agents/skills/gravity-ui/rules/hallucination-traps.md DELETED Viewed

@@ -1,361 +0,0 @@
-# Hallucination traps — Incorrect / Correct pairs
-Read this before using any Gravity UI component API you are not 100% sure of.
-These are the APIs agents invent most often — each pair shows the wrong guess,
-the correct form, and *why*. The references under `references/` cover the
-ground truth (full token tables, prop lists); this file is the shortcut to not
-falling into the common holes.
-Per-component traps (a specific `Table`, `Button`, `Chart` prop) live in each
-package's own `dist/docs/INDEX.md` — read that for component detail. This file
-covers the **cross-cutting** traps that affect every `@gravity-ui/*` package.
----
-## Typography
-### `header-3`…`header-6` do not exist
-❌ **Incorrect** — invented scale:
-```tsx
-<Text variant="header-3">Section title</Text>
-<Text variant="header-4">Subsection</Text>
-<Heading size="lg">Page title</Heading>   // also: there is no `Heading` component
-```
-✓ **Correct** — the real `Text` variants:
-```tsx
-<Text variant="header-1">Page title</Text>
-<Text variant="header-2">Section title</Text>
-<Text variant="subheader-1">Subsection</Text>   {/* or subheader-2/3 */}
-<Text variant="display-1">Hero</Text>           {/* display-1…4 are larger than headers */}
-```
-**Why:** only `header-1` and `header-2` exist. Above them sit `display-1…4`,
-below them `subheader-1…3`. Body variants are `body-1`/`body-2`/`body-3`
-(plus `body-short`), and small text is `caption-1`/`caption-2`. There is no
-standalone `Heading` component — headings are `<Text variant="…">`. Setting a
-size via inline `fontSize` is also wrong; pick the variant.
-### Page title is a `Text`, not an `<h1>`
-❌ `<h1>Dashboard</h1>`
-✓ `<Text variant="header-1">Dashboard</Text>`
-**Why:** the design system's metrics (font-family, weight, line-height, tracking)
-come from `--g-text-header-1-*` tokens. A raw `<h1>` bypasses them and renders
-with the browser default.
----
-## Layout — the flex contract
-### `Flex`/`Box` have no `padding` / `margin` props
-❌ **Incorrect** — MUI-style props (do not exist):
-```tsx
-<Flex p={4} mb={3}>…</Flex>
-<Box padding="16px" marginTop={2}>…</Box>
-```
-✓ **Correct** — use `gap` between children, `spacing()` / `sp()` for offsets:
-```tsx
-import {Flex, sp} from '@gravity-ui/uikit';
-<Flex gap={4}>                       {/* 16px between children */}
-  <Button />
-  <Button />
-</Flex>
-<div className={sp({p: 4, mb: 3})}>…</div>   {/* padding + margin-bottom */}
-```
-**Why:** `Flex`/`Box` only expose `gap` (a spacing-scale step `0…10`, halves
-allowed: `0.5`, `1.5`…). For everything else use the `spacing()` (or `sp()`)
-utility, which returns a className, or the raw `--g-spacing-*` variables in
-CSS. Never hard-code pixel values.
-### In a row, explicitly assign who flexes and who holds
-❌ **Incorrect** — relying on flex defaults:
-```tsx
-<Flex alignItems="center">
-  <Avatar />                {/* gets crushed when text is long */}
-  <span>{veryLongName}</span>
-  <Button>Edit</Button>     {/* also gets crushed */}
-</Flex>
-```
-✓ **Correct** — fix-elements get `flex-shrink: 0`, the flexible middle gets
-`flex: 1; min-width: 0`:
-```tsx
-<Flex alignItems="center" gap={2}>
-  <Avatar style={{flexShrink: 0}} />
-  <span style={{flex: 1, minWidth: 0}}>{veryLongName}</span>
-  <Button style={{flexShrink: 0}}>Edit</Button>
-</Flex>
-```
-**Why:** flex defaults are `flex-shrink: 1` and `min-width: auto` on every
-child — both work against you. Without `flex-shrink: 0`, fix-sized elements
-(avatars, icons, badges, the right-aligned action button) get squashed when a
-sibling is long. Without `min-width: 0` on the flexible child, the flex
-`min-width: auto` prevents it from shrinking and the text overflows the
-container / overlaps its siblings — and this is invisible to layout tests
-because the element's bounding box stays clean. The fix-elements are what
-should hold their size; compression goes into the flexible element (text gets
-truncated, breadcrumbs collapse to `…`, a list scrolls).
-The same contract applies vertically: panels `flex: 1; min-height: 0`;
-terminal zones (header / footer / composer) `flex-shrink: 0`.
-### Horizontal scroll lives inside the widget, not the page
-❌ **Incorrect** — wrap the whole workspace:
-```tsx
-<div style={{overflowX: 'auto'}}>      {/* breaks sticky headers, sidebars */}
-  <Workspace />
-</div>
-```
-✓ **Correct** — wrap only the wide widget, give the content its honest
-`min-width`:
-```tsx
-<div style={{overflowX: 'auto', maxWidth: '100%'}}>
-  <WideTable style={{minWidth: 1200}} />
-</div>
-```
-**Why:** wrapping the whole workspace makes sticky columns/headers and the
-sidebar scroll horizontally too. Compression should go into scroll on the
-container of the wide thing only.
-For a full-height app frame: root `height: 100vh` (+ a sane `min-height`),
-panels `flex: 1; min-height: 0; overflow-y: auto` — the panel scrolls, not the
-document.
----
-## Theming
-### Styles + fonts are required; order matters
-❌ **Incorrect** — missing imports, or theme before base:
-```tsx
-import './theme.css';                                  // before styles.css → gets overwritten
-import {ThemeProvider} from '@gravity-ui/uikit';
-// no styles.css, no fonts.css → components render unstyled
-```
-✓ **Correct**:
-```tsx
-import '@gravity-ui/uikit/styles/fonts.css';           // fonts first
-import '@gravity-ui/uikit/styles/styles.css';          // then base
-import './theme.css';                                  // custom ALWAYS after styles.css
-import {ThemeProvider} from '@gravity-ui/uikit';
-```
-**Why:** without `styles.css` + `fonts.css` imported once at the entry point,
-every component renders unstyled. A custom theme file imported *before*
-`styles.css` is overwritten by it in the cascade — custom always comes after.
-### `theme` takes five values — no `"default"` or `"auto"`
-❌ `<ThemeProvider theme="default">`
-❌ `<ThemeProvider theme="auto">`
-✓ `<ThemeProvider theme="light">` / `"dark"` / `"light-hc"` / `"dark-hc"`
-✓ `<ThemeProvider theme="system">` (resolves to light/dark from OS preference)
-### Branding means a full token set, on both themes — never 2–4 tokens
-❌ **Incorrect** — partial override:
-```css
-.g-root { --g-color-base-brand: #007AFF; }
-```
-✓ **Correct** — override the full brand group, per theme:
-```css
-.g-root_theme_light {
-  --g-color-base-brand: #007AFF;
-  --g-color-base-brand-hover: #0066D6;
-  --g-color-base-selection: rgba(0, 122, 255, 0.05);
-  --g-color-base-selection-hover: rgba(0, 122, 255, 0.1);
-  --g-color-line-brand: #007AFF;
-  --g-color-text-brand: #007AFF;
-  --g-color-text-brand-contrast: #FFFFFF;   /* required: text on brand bg */
-  --g-color-text-link: #007AFF;
-  --g-color-text-link-hover: #0066D6;
-}
-.g-root_theme_dark {
-  /* different values — dark usually needs a brighter brand */
-  --g-color-base-brand: #2E8BFF;
-  /* … same set, dark-tuned … */
-}
-```
-**Why:** the semantic layer has many tokens pointing at "brand" — selection,
-focus, links, the contrast text on a brand background. Override only
-`--g-color-base-brand` and you get a UI where the button is branded but
-selection, links and focus rings are still the default accent. Provide the full
-set, and provide it for *each* theme you support (dark themes usually need a
-brighter brand than light). Forgetting `--g-color-text-brand-contrast` makes
-text on a brand button unreadable.
-Better than hand-writing: generate the full set with the
-[Themer](https://gravity-ui.com/themer) web tool or
-[`@gravity-ui/uikit-themer`](https://github.com/gravity-ui/uikit-themer) — both
-recalculate the dependent palette from a single base color.
-### A nested `ThemeProvider` without `scoped` does not scope
-❌ **Incorrect** — expects a local dark section:
-```tsx
-<ThemeProvider theme="dark">   {/* no scoped → writes to document.body globally */}
-  <Toolbar />
-</ThemeProvider>
-```
-✓ **Correct**:
-```tsx
-<ThemeProvider scoped theme="dark">
-  <Toolbar />
-</ThemeProvider>
-```
-**Why:** an un-scoped `ThemeProvider` writes the theme class to `document.body`
-— globally, last-wins — not into the subtree. The `scoped` prop renders a
-dedicated `<div class="g-root g-root_theme_dark">` around the children *and*
-updates the theme React context (so `useTheme` inside the section sees the
-section's theme). For a CSS-only region without context, apply the class
-manually: `<div className={getRootClassName({theme: 'dark'})}>`.
-### Controls on a brand/colored background: fixed contrast, both themes
-❌ **Incorrect** — default button on a brand-colored hero:
-```tsx
-<section style={{background: 'var(--g-color-base-brand)'}}>
-  <Button>Sign up</Button>   {/* default view follows theme → low contrast on bright bg */}
-</section>
-```
-✓ **Correct** — pick a `view` with its own contrasting surface, or scope a CSS
-override fixing contrast for both themes:
-```tsx
-<section style={{background: 'var(--g-color-base-brand)'}}>
-  <Button view="raised">Sign up</Button>   {/* solid contrasting surface */}
-</section>
-```
-**Why:** a brand-colored fill is usually the *same* color in light and dark
-(it's a fill, not a themed surface), so the control on top should keep a fixed
-contrast in both themes rather than lightening/darkening with the theme. Try a
-`view` with its own surface (`raised`, `action`); if none fits, override the
-component's CSS API (`--g-button-background-color`, `--g-button-text-color`, …)
-scoped to the section, with contrast values for both themes. This is distinct
-from `--g-color-text-brand-contrast`, which is about text on a *brand button*
-(`view="action"`).
-### Customization ladder — descend only when there's no higher handle
-When you need to change how a Gravity UI component looks, try in this order:
-1. **Global tokens** (`--g-*` semantic tokens / theme) — change the look
-   everywhere by changing the token, not components one by one.
-2. **Component's own CSS API** (`--g-button-*`, `--g-card-border-radius`,
-   `--g-text-input-*`, …) — scoped to the wrapper / class of the spot you're
-   changing. Check the component's README for the variables it exposes.
-3. **A narrow, flagged hack** — a custom class on a specific internal element,
-   with a comment "hack on internal classes, pinned to version <X>", and a note
-   to upstream it. Only after confirming step 1 and 2 don't expose a handle.
-4. **NEVER** broad structural matches: `[class*='…']` or ID selectors against
-   internal markup. Such an override is written against one specific DOM
-   structure and breaks silently when it changes.
-**Why:** a `[class*='…']` override that worked yesterday breaks tomorrow when
-the component adds a wrapper or renames an internal class — and you won't get a
-type error, just a visually broken layout. Always start at the top of the
-ladder; descend one rung only when the rung above has no handle.
----
-## Color & shape
-### Use semantic tokens, never raw hex or private tokens
-❌ `color: #1677FF`
-❌ `background: var(--g-color-private-blue-500)`
-✓ `color: var(--g-color-text-link)`
-✓ `background: var(--g-color-base-brand)`
-**Why:** Gravity UI's color system is two-layered. The *private* layer
-(`--g-color-private-<hue>-<step>`) is the raw palette — an implementation
-detail that can change, never reference it directly. The *semantic* layer
-(`--g-color-{group}-{role}`) encodes intent and is theme-aware. Use it:
-- backgrounds/fills: `--g-color-base-*` (`base-background`, `base-brand`,
-  `base-generic`, `base-danger-*`, …)
-- text/icons: `--g-color-text-*` (`text-primary`, `text-secondary`, `text-hint`,
-  `text-brand`, `text-link`, …)
-- borders/lines: `--g-color-line-*` (`line-generic`, `line-brand`, `line-focus`,
-  `line-danger`)
-- effects: `--g-color-sfx-*` (`sfx-shadow`, `sfx-veil`, `sfx-fade`)
-For text on a brand/colored background, use `--g-color-text-brand-contrast`
-(not the plain brand color — it has no contrast guarantee).
-### Border radius uses a token, never a hard-coded `px`
-❌ `border-radius: 8px`
-✓ `border-radius: var(--g-border-radius-m)`
-**Why:** the scale is `--g-border-radius-{xs|s|m|l|xl}`. Components expose
-their own radius variable on the same scale (`--g-button-border-radius`,
-`--g-card-border-radius`, `--g-modal-border-radius`, …) so you can tune one
-component without moving the global scale. Use a token, always.
----
-## Component-prop traps (cross-cutting)
-### `Button` uses `view`, not `variant` / `color`
-❌ `<Button variant="primary">` / `<Button color="primary">`
-✓ `<Button view="action">` (also `outlined`, `flat`, `raised`, `normal`,
-   `special`, `clear`)
-### `Icon` takes an object via `data`, never a string name
-❌ `<Icon name="check" />` / `<Icon data="Check" />`
-✓ `<Icon data={CheckIcon} size={16} />`
-**Why:** `Icon` (from `@gravity-ui/uikit`) is the *renderer*; the glyphs live
-in `@gravity-ui/icons` as React components. There is no `name` prop. Pass the
-imported component object through `data`. Never guess an icon name — use
-`scripts/icon-image-search.sh` (reverse image search) or look it up at
-`gravity-ui.com/icons`. See `references/icons.md`.
----
-## When in doubt
-1. Read `references/theming.md` (full token tables) and
-   `references/layout.md` (spacing scale, breakpoints).
-2. Read the chosen package's `dist/docs/INDEX.md` for component-specific props.
-3. If still unsure, ask the user rather than guessing — invented APIs are the
-   single biggest source of broken Gravity UI code.