@jetbrains/ring-ui 7.0.122 → 7.0.123-beta.0

package/README.md

@@ -13,6 +13,10 @@
 
 This collection of UI components aims to provide all the necessary building blocks for web-based products built inside JetBrains, as well as third-party plugins developed for JetBrains' products.
 
+## Guidance for coding agents
+
+The npm packages include [`skills/ring-ui/SKILL.md`](./skills/ring-ui/SKILL.md), which teaches coding agents to consume Ring UI through `@jetbrains/ring-ui-built` when composing complete pages, responsive layouts, forms, themes, and feedback. The same Skill files are published in both npm artifacts.
+
 ## Try now
 * Try the [codesandbox](https://codesandbox.io/p/sandbox/ring-ui-7-0-demo-z6v6ym), based on `create-react-app` tooling, to see and try the UI components
 * Check out [list of examples](https://jetbrains.github.io/ring-ui/master/index.html) for each component

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jetbrains/ring-ui",
-  "version": "7.0.122",
+  "version": "7.0.123-beta.0",
   "description": "JetBrains UI library",
   "author": {
     "name": "JetBrains"
@@ -11,6 +11,7 @@
     "babel.config.js",
     "components",
     "postcss.config.js",
+    "skills",
     "webpack.config.js",
     "typings.d.ts"
   ],
@@ -68,7 +69,7 @@
     "prebuild": "rimraf components && npm run prebuild:tsc && cpy './**/*' '!**/*.stories.*' '!**/*.figma.*' '!**/*.ts' '!**/*.tsx' '!**/test-helpers/mocks/**' ../components --parents --cwd=src/",
     "prebuild:tsc": "(npm run type-check:create-d-ts && tsc --project tsconfig-build.json) ; npm run type-check:cleanup-d-ts",
     "prepare": "webpack -c .storybook/custom-header/webpack.config.js",
-    "prepublishOnly": "pinst --disable",
+    "prepublishOnly": "npm run verify-package-skills && pinst --disable",
     "prerelease-built-ci": "node scripts/prepare-built-package.js",
     "prerelease-ci": "git pull",
     "release-built-ci": "npm publish --access=public $NPM_PUBLISH_PARAMS",
@@ -83,6 +84,7 @@
     "stylelint": "stylelint --ignore-path .stylelintignore '**/*.css'",
     "stylelint-ci": "stylelint --ignore-path .stylelintignore --custom-formatter 'scripts/jslint-xml.js' '**/*.css' | xmlappend eslint-report.xml",
     "test": "vitest src",
+    "verify-package-skills": "node scripts/verify-package-skills.mjs",
     "type-check": "(npm run type-check:create-d-ts && npm run type-check:main && npm run type-check:build) ; npm run type-check:cleanup-d-ts",
     "type-check:create-d-ts": "npx tcm src && npx tcm .storybook",
     "type-check:main": "tsc --noEmit -p tsconfig.json",

package/skills/ring-ui/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: ring-ui
+description: Use when implementing, laying out, theming, validating, or troubleshooting React interfaces that use @jetbrains/ring-ui-built.
+---
+
+# Ring UI
+
+Use Ring UI for controls, surfaces, and design tokens. Let semantic HTML and native CSS Flexbox/Grid own page structure and geometry.
+
+## When to use
+
+Use this skill for React pages, settings forms, dialogs, navigation, responsive composition, themes, loading/empty/error states, or accessibility work in a project that uses or is being set up to use `@jetbrains/ring-ui-built`.
+
+Do not use it for non-React interfaces, projects that neither use nor are being set up to use Ring UI, or product-specific YouTrack infrastructure. Do not introduce Ring UI merely to solve generic page layout.
+
+## Workflow
+
+1. Before initializing or laying out an application, read [references/page-layouts.md](references/page-layouts.md) and follow its app setup, even if `@jetbrains/ring-ui-built` is not installed yet.
+2. If the package is installed, inspect `package.json` and the lockfile for its exact version. Read its `README.md` and relevant `.d.ts` files before choosing imports or props.
+3. Import components only from `@jetbrains/ring-ui-built`. Compose Ring controls and surfaces inside semantic landmarks, and use native CSS Flexbox/Grid for page geometry and CSS media/container queries for responsiveness.
+4. Use `--ring-*` tokens for colors, typography, borders, and spacing based on `--ring-unit`. Do not copy their resolved values.
+5. Model form draft, saved, validation, submission, and result state explicitly. Distinguish blocking loading, local loading, background work, first-use empty, filtered empty, success, warning, and retryable failure.
+
+## Preferred patterns
+
+- Use one semantic `h1`, clear landmarks, native anchors for navigation, and native/Ring buttons for actions. Do not make clickable `div` elements.
+- Prefer `Input`'s own `label`. Give externally labelled controls stable IDs and connect `htmlFor`, `aria-describedby`, and errors explicitly.
+- Keep `Select` controlled and explicitly generic: use `Select<T>` with `SelectItem<T>[]` data, selected item, and `onChange` argument—never `Select<SelectItem<T>>` or guessed primitive values.
+- Wrap error `Banner` content in `role="alert"`, non-urgent status/success content in `role="status"`, blocking `LoaderScreen` content in a named status region, and local `LoaderInline` content in a named status region. Avoid announcing background work that does not affect the user.
+- Use CSS Modules. Put `min-width: 0` on shrinking grid/flex children, `min-height: 0` where vertical flex children scroll, and assign each axis to one explicit scroll owner.
+- Use CSS media queries for page-wide geometry and container queries for reusable components. Branch in React only when interaction or content structure must change.
+- Never style Ring UI internal classes or `data-test` attributes. Treat test hooks as behavior selectors, not CSS APIs.
+
+Do not add new uses of Ring UI's deprecated `Grid`/`Row`/`Col` or `ContentLayout`. Do not copy product-specific YouTrack wrappers such as `ButtonLegacy` or `IconLegacy`, page shells, portals, sticky stacks, form wrappers, or alert services into package consumers.
+
+## Common tasks
+
+- App setup, page shells, responsive navigation, sticky regions, and scroll ownership: read [references/page-layouts.md](references/page-layouts.md).
+- Forms, validation, dirty state, async saving, and page feedback: read [references/forms-and-feedback.md](references/forms-and-feedback.md).
+
+## Validation
+
+Run the consuming repository's type-check, focused tests, lint, and production build equivalents. Interactively check near `1280x800` and `390x844`: accessible names and keyboard order, every state transition and action, page and popup overflow, heading hierarchy, theme behavior, and the browser console.

package/skills/ring-ui/references/forms-and-feedback.md

@@ -0,0 +1,261 @@
+# Forms and feedback
+
+Use a native `<form>` as the composition root. Ring UI supplies controls and feedback surfaces; React owns the saved snapshot, draft, validation, submission, and result states.
+
+The example and consumer imports use `@jetbrains/ring-ui-built`.
+
+## Contents
+
+- [Complete controlled settings form](#complete-controlled-settings-form)
+- [Form-state rules](#form-state-rules)
+- [Page-state decisions](#page-state-decisions)
+
+## Complete controlled settings form
+
+`project-settings-form.tsx`:
+
+```tsx
+import {useState, type FormEvent} from 'react';
+import Banner from '@jetbrains/ring-ui-built/components/banner/banner';
+import Button from '@jetbrains/ring-ui-built/components/button/button';
+import ButtonSet from '@jetbrains/ring-ui-built/components/button-set/button-set';
+import ControlLabel from '@jetbrains/ring-ui-built/components/control-label/control-label';
+import Input from '@jetbrains/ring-ui-built/components/input/input';
+import Select, {type SelectItem} from '@jetbrains/ring-ui-built/components/select/select';
+import Toggle from '@jetbrains/ring-ui-built/components/toggle/toggle';
+
+import styles from './project-settings-form.module.css';
+
+type Visibility = 'private' | 'team' | 'public';
+
+type VisibilityData = {
+  value: Visibility;
+};
+
+type Settings = {
+  name: string;
+  visibility: Visibility;
+  notifications: boolean;
+};
+
+type ProjectSettingsFormProps = {
+  initialValue: Settings;
+  onSave: (value: Settings) => Promise<void>;
+};
+
+const VISIBILITY_OPTIONS: SelectItem<VisibilityData>[] = [
+  {key: 'private', label: 'Private', value: 'private'},
+  {key: 'team', label: 'Team', value: 'team'},
+  {key: 'public', label: 'Public', value: 'public'},
+];
+
+const NAME_ID = 'project-settings-name';
+const NAME_HELP_ID = 'project-settings-name-help';
+const NAME_ERROR_ID = 'project-settings-name-error';
+const VISIBILITY_ID = 'project-settings-visibility';
+const NOTIFICATIONS_ID = 'project-settings-notifications';
+
+export function ProjectSettingsForm({initialValue, onSave}: ProjectSettingsFormProps) {
+  const [saved, setSaved] = useState(initialValue);
+  const [draft, setDraft] = useState(initialValue);
+  const [submitting, setSubmitting] = useState(false);
+  const [showErrors, setShowErrors] = useState(false);
+  const [savedMessage, setSavedMessage] = useState<string | null>(null);
+  const [saveError, setSaveError] = useState<string | null>(null);
+
+  const nameError = draft.name.trim() ? null : 'Project name is required.';
+  const dirty =
+    draft.name !== saved.name ||
+    draft.visibility !== saved.visibility ||
+    draft.notifications !== saved.notifications;
+  const selectedVisibility =
+    VISIBILITY_OPTIONS.find(option => option.value === draft.visibility) ?? null;
+
+  const updateDraft = (next: Settings) => {
+    setDraft(next);
+    setSavedMessage(null);
+    setSaveError(null);
+  };
+
+  const handleSubmit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    if (submitting) return;
+
+    setShowErrors(true);
+    setSavedMessage(null);
+    setSaveError(null);
+    if (nameError) return;
+
+    const next = {...draft, name: draft.name.trim()};
+    setSubmitting(true);
+    try {
+      await onSave(next);
+      setSaved(next);
+      setDraft(next);
+      setShowErrors(false);
+      setSavedMessage('Project settings saved.');
+    } catch {
+      setSaveError('Could not save project settings. Try again.');
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const handleCancel = () => {
+    setDraft(saved);
+    setShowErrors(false);
+    setSavedMessage(null);
+    setSaveError(null);
+  };
+
+  const nameDescribedBy =
+    showErrors && nameError ? `${NAME_HELP_ID} ${NAME_ERROR_ID}` : NAME_HELP_ID;
+
+  return (
+    <form className={styles.form} onSubmit={handleSubmit} noValidate>
+      {saveError && (
+        <div role="alert">
+          <Banner mode="error" withIcon>
+            {saveError}
+          </Banner>
+        </div>
+      )}
+      {savedMessage && (
+        <div role="status">
+          <Banner mode="success" withIcon>
+            {savedMessage}
+          </Banner>
+        </div>
+      )}
+
+      <div className={styles.field}>
+        <Input
+          id={NAME_ID}
+          label="Project name"
+          value={draft.name}
+          required
+          disabled={submitting}
+          aria-invalid={showErrors && Boolean(nameError)}
+          aria-describedby={nameDescribedBy}
+          error={showErrors && nameError ? '' : undefined}
+          onChange={event => updateDraft({...draft, name: event.currentTarget.value})}
+        />
+        <p id={NAME_HELP_ID} className={styles.help}>
+          Shown in project navigation and search.
+        </p>
+        {showErrors && nameError && (
+          <p id={NAME_ERROR_ID} className={styles.error}>
+            {nameError}
+          </p>
+        )}
+      </div>
+
+      <div className={styles.field}>
+        <Select<VisibilityData>
+          id={VISIBILITY_ID}
+          data={VISIBILITY_OPTIONS}
+          selected={selectedVisibility}
+          selectedLabel="Visibility"
+          label="Choose visibility"
+          disabled={submitting}
+          onChange={(option: SelectItem<VisibilityData> | null) => {
+            if (option) updateDraft({...draft, visibility: option.value});
+          }}
+        />
+        <p className={styles.help}>Controls who can discover and open this project.</p>
+      </div>
+
+      <div className={styles.toggleField}>
+        <ControlLabel htmlFor={NOTIFICATIONS_ID} disabled={submitting}>
+          Email notifications
+        </ControlLabel>
+        <Toggle
+          id={NOTIFICATIONS_ID}
+          checked={draft.notifications}
+          disabled={submitting}
+          onChange={event => updateDraft({...draft, notifications: event.currentTarget.checked})}
+        />
+      </div>
+
+      {dirty && (
+        <ButtonSet className={styles.actions}>
+          <Button primary type="submit" loader={submitting} disabled={submitting}>
+            Save
+          </Button>
+          <Button type="button" disabled={submitting} onClick={handleCancel}>
+            Cancel
+          </Button>
+        </ButtonSet>
+      )}
+    </form>
+  );
+}
+```
+
+`project-settings-form.module.css`:
+
+```css
+.form {
+  display: grid;
+  width: min(100%, calc(var(--ring-unit) * 75));
+  gap: calc(var(--ring-unit) * 3);
+}
+
+.field {
+  display: grid;
+  gap: calc(var(--ring-unit) / 2);
+  min-width: 0;
+}
+
+.help,
+.error {
+  margin: 0;
+  font-size: var(--ring-font-size-smaller);
+  line-height: var(--ring-line-height-lowest);
+}
+
+.help {
+  color: var(--ring-secondary-color);
+}
+
+.error {
+  color: var(--ring-error-color);
+}
+
+.toggleField {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: calc(var(--ring-unit) * 2);
+  padding-block: var(--ring-unit);
+}
+
+.actions {
+  padding-block-start: calc(var(--ring-unit) * 2);
+  border-block-start: 1px solid var(--ring-line-color);
+}
+```
+
+## Form-state rules
+
+- Keep persisted `saved` data separate from editable `draft`. Derive validity, dirty state, and the selected `SelectItem` instead of storing duplicates.
+- React only uses `initialValue` for the first `useState` call. If the mounted form can switch records or receive a server refresh, resynchronize `saved` and `draft` from a stable record ID/version. Decide explicitly whether a dirty draft wins, is discarded, or requires confirmation; do not reset on every new object reference.
+- Add an unsaved-navigation guard when leaving the route, closing a sidebar, or dismissing a dialog could destroy a dirty draft. Remove the guard after save or cancel.
+- Keep field rules close to their derived errors. Reveal errors on submit or blur, retain persistent help, connect all help/error IDs with `aria-describedby`, and move focus to the first invalid field when long forms can fail off-screen.
+- Prevent duplicate submission in both the handler and controls. While saving, propagate `disabled` to every editable control, external label/help action, Save, Cancel, and dependent section; use the primary button's `loader` for local progress.
+- Put actions after page fields for ordinary pages, in the owning sidebar's sticky/footer region for sidebar editors, and in the dialog action area for dialogs. Keep them inside the native form so Enter submits predictably.
+
+## Page-state decisions
+
+| State | Use | Accessibility and behavior |
+| --- | --- | --- |
+| Blocking loading | `LoaderScreen` in the main region | Give the region `role="status"` and an accessible loading name; replace it with content when ready. |
+| Local loading | `LoaderInline` beside the affected section/control | Name the local status; keep unrelated content and actions usable. |
+| Background loading | Subtle inline progress only when users need it | Do not block the page or repeatedly announce silent refreshes. |
+| Initial empty | Purpose, short explanation, and primary creation/setup action | Distinguish absence of data from an error. |
+| Filtered empty | “No matches” plus clear/change-filter action | Preserve the user's data and current filter context. |
+| Contextual risk | Persistent warning/error `Banner` near the affected controls | Use `role="alert"` only when immediate interruption is warranted. |
+| Success | `Banner` or message in `role="status"` near the saved region | Confirm the completed action without moving focus. |
+| Retryable failure | Error `Banner` in `role="alert"` with a retry path | Preserve the draft, stop the loader, and re-enable controls. |
+
+Avoid uncontrolled forms that also maintain a shared saved snapshot, untyped `Select` values or guessed primitive selections, duplicate submission paths, inaccessible labels/help, conflating first-use and filtered empty states, and transient alerts as a replacement for persistent field validation.

package/skills/ring-ui/references/page-layouts.md

@@ -0,0 +1,324 @@
+# Page layouts
+
+Ring UI supplies controls, surfaces, and tokens. It does not replace page geometry: semantic HTML defines the document, while native CSS Grid/Flexbox defines the shell, widths, responsive behavior, sticky regions, and scroll ownership.
+
+The examples and consumer imports use `@jetbrains/ring-ui-built`.
+
+## Contents
+
+- [App setup](#app-setup)
+- [Complete page shell](#complete-page-shell)
+- [Geometry rules](#geometry-rules)
+- [Sticky offsets and nested scopes](#sticky-offsets-and-nested-scopes)
+- [Theme, semantics, and accessibility](#theme-semantics-and-accessibility)
+
+## App setup
+
+Use the repository's package manager to install the built package. For example, with npm:
+
+```shell
+npm install @jetbrains/ring-ui-built
+```
+
+Import the consolidated stylesheet exactly once at the application entry point. Import components from the same package, and put `ThemeProvider` near the application root with `Theme.AUTO` and `passToPopups`:
+
+```tsx
+import {createRoot} from 'react-dom/client';
+import '@jetbrains/ring-ui-built/components/style.css';
+import Theme, {ThemeProvider} from '@jetbrains/ring-ui-built/components/global/theme';
+
+import App from './App';
+
+const rootElement = document.getElementById('root');
+if (!rootElement) {
+  throw new Error('Root element #root was not found.');
+}
+
+const root = createRoot(rootElement);
+
+root.render(
+  <ThemeProvider theme={Theme.AUTO} passToPopups target={document.body}>
+    <App />
+  </ThemeProvider>,
+);
+```
+
+Add `class="plugin"` to `<body>`:
+
+```html
+<body class="plugin">
+  <div id="root"></div>
+</body>
+```
+
+Add the baseline page styles to application CSS:
+
+```css
+body.plugin {
+  padding: 0 16px;
+  background-color: var(--ring-content-background-color);
+  color: var(--ring-text-color);
+  font-size: var(--ring-font-size);
+}
+```
+
+A deliberately full-bleed shell can override the body padding in application CSS.
+
+## Complete page shell
+
+`page-shell.tsx`:
+
+```tsx
+import type {ReactNode} from 'react';
+import Button from '@jetbrains/ring-ui-built/components/button/button';
+import {H1} from '@jetbrains/ring-ui-built/components/heading/heading';
+
+import styles from './page-shell.module.css';
+
+type PageShellProps = {
+  children: ReactNode;
+  currentPath: string;
+  onCreateProject: () => void;
+};
+
+const primaryNavigation = [
+  {href: '/projects', label: 'Projects'},
+  {href: '/teams', label: 'Teams'},
+];
+
+const settingsNavigation = [
+  {href: '/projects/settings/general', label: 'General'},
+  {href: '/projects/settings/access', label: 'Access'},
+  {href: '/projects/settings/integrations', label: 'Integrations'},
+];
+
+export function PageShell({children, currentPath, onCreateProject}: PageShellProps) {
+  return (
+    <div className={styles.shell}>
+      <a className={styles.skipLink} href="#main-content">
+        Skip to content
+      </a>
+
+      <header className={styles.topBar}>
+        <a className={styles.brand} href="/" aria-label="Acme home">
+          Acme
+        </a>
+        <nav className={styles.topNavigation} aria-label="Primary">
+          {primaryNavigation.map(item => (
+            <a
+              key={item.href}
+              className={styles.navigationLink}
+              href={item.href}
+              aria-current={currentPath === item.href ? 'page' : undefined}
+            >
+              {item.label}
+            </a>
+          ))}
+        </nav>
+        <Button primary onClick={onCreateProject}>
+          New project
+        </Button>
+      </header>
+
+      <div className={styles.workspace}>
+        <aside className={styles.sidebar}>
+          <nav className={styles.sidebarNavigation} aria-label="Project settings">
+            {settingsNavigation.map(item => (
+              <a
+                key={item.href}
+                className={styles.sidebarLink}
+                href={item.href}
+                aria-current={currentPath === item.href ? 'page' : undefined}
+              >
+                {item.label}
+              </a>
+            ))}
+          </nav>
+        </aside>
+
+        <main id="main-content" className={styles.main} tabIndex={-1}>
+          <div className={styles.content}>
+            <H1>Project settings</H1>
+            {children}
+          </div>
+        </main>
+      </div>
+    </div>
+  );
+}
+```
+
+`page-shell.module.css`:
+
+```css
+.shell {
+  --page-top-offset: calc(var(--ring-unit) * 8);
+
+  min-height: 100dvh;
+  color: var(--ring-text-color);
+  background: var(--ring-content-background-color);
+}
+
+.skipLink {
+  position: absolute;
+  z-index: 20;
+  inset-block-start: var(--ring-unit);
+  inset-inline-start: var(--ring-unit);
+  padding: var(--ring-unit) calc(var(--ring-unit) * 2);
+  color: var(--ring-link-color);
+  background: var(--ring-content-background-color);
+  border: 1px solid var(--ring-borders-color);
+  transform: translateY(-200%);
+}
+
+.skipLink:focus {
+  transform: none;
+}
+
+.topBar {
+  position: sticky;
+  z-index: 10;
+  inset-block-start: 0;
+  display: flex;
+  min-height: var(--page-top-offset);
+  align-items: center;
+  gap: calc(var(--ring-unit) * 2);
+  padding-inline: calc(var(--ring-unit) * 4);
+  background: var(--ring-navigation-background-color);
+  border-block-end: 1px solid var(--ring-line-color);
+}
+
+.brand {
+  flex: none;
+  color: var(--ring-text-color);
+  font-weight: bold;
+  text-decoration: none;
+}
+
+.topNavigation {
+  display: flex;
+  flex: 1;
+  flex-wrap: wrap;
+  gap: var(--ring-unit) calc(var(--ring-unit) * 2);
+  min-width: 0;
+}
+
+.navigationLink,
+.sidebarLink {
+  color: var(--ring-link-color);
+}
+
+.navigationLink[aria-current='page'],
+.sidebarLink[aria-current='page'] {
+  color: var(--ring-text-color);
+  font-weight: bold;
+  text-decoration: none;
+}
+
+.workspace {
+  display: grid;
+  grid-template-columns: calc(var(--ring-unit) * 30) minmax(0, 1fr);
+  min-height: calc(100dvh - var(--page-top-offset));
+}
+
+.sidebar {
+  position: sticky;
+  inset-block-start: var(--page-top-offset);
+  align-self: start;
+  padding: calc(var(--ring-unit) * 3);
+  background: var(--ring-sidebar-background-color);
+  border-inline-end: 1px solid var(--ring-line-color);
+}
+
+.sidebarNavigation {
+  display: flex;
+  flex-direction: column;
+  gap: var(--ring-unit);
+}
+
+.main {
+  min-width: 0;
+  padding: calc(var(--ring-unit) * 4);
+}
+
+.content {
+  width: min(100%, calc(var(--ring-unit) * 120));
+  margin-inline: auto;
+}
+
+@media (max-width: 760px) {
+  .shell {
+    --page-top-offset: 0px;
+  }
+
+  .topBar {
+    position: static;
+    flex-wrap: wrap;
+    padding: calc(var(--ring-unit) * 2);
+  }
+
+  .topNavigation {
+    order: 3;
+    flex-basis: 100%;
+  }
+
+  .workspace {
+    grid-template-columns: minmax(0, 1fr);
+    min-height: 0;
+  }
+
+  .sidebar {
+    position: static;
+    min-width: 0;
+    padding: var(--ring-unit) calc(var(--ring-unit) * 2);
+    overflow-x: auto;
+    border-inline-end: 0;
+    border-block-end: 1px solid var(--ring-line-color);
+  }
+
+  .sidebarNavigation {
+    width: max-content;
+    flex-direction: row;
+    gap: calc(var(--ring-unit) * 2);
+  }
+
+  .main {
+    padding: calc(var(--ring-unit) * 2);
+  }
+}
+```
+
+## Geometry rules
+
+- Use `--ring-unit` as the spacing base and semantic tokens such as `--ring-content-background-color`, `--ring-sidebar-background-color`, `--ring-text-color`, and `--ring-line-color`. Do not paste their current pixel or color values into application CSS.
+- In Grid/Flexbox, `min-width: auto` can stop content from shrinking and `min-height: auto` can stop vertical children from scrolling. Put `min-width: 0` or `min-height: 0` on the child that must shrink.
+- Assign exactly one scroll owner per axis and scope. Prefer document scrolling for a page; use a named inner owner only for a deliberate viewport-like region. The mobile sidebar above owns only its horizontal overflow. A dialog or portal is a separate scroll scope.
+- Bound long-form reading content rather than stretching it across the viewport. Choose a product-appropriate token-multiple maximum; allow tables, canvases, and dense dashboards to use a wider explicit region.
+- Use CSS media queries when only geometry changes. Branch in React when narrow layouts need different interaction, focus order, or content—not to reproduce `display`, wrapping, or column changes.
+- Use container queries for reusable widgets whose layout depends on their allocated panel width. Give the wrapper `container-type: inline-size` and keep viewport queries for the outer application shell.
+
+## Sticky offsets and nested scopes
+
+Prefer a simple inherited CSS variable when sticky heights are known:
+
+```css
+.page {
+  --sticky-offset: calc(var(--ring-unit) * 8);
+}
+
+.localToolbar {
+  position: sticky;
+  inset-block-start: var(--sticky-offset);
+}
+```
+
+Measure in JavaScript only when the preceding sticky height is genuinely dynamic; publish the measured value as a CSS variable instead of calculating every child position in React. Keep portal and dialog scroll containers isolated: their sticky offsets begin at that scope's top, not the document header.
+
+## Theme, semantics, and accessibility
+
+- Put `ThemeProvider` near the application root and use `Theme.AUTO`; use `passToPopups` when popup content must inherit the theme. Keep token-based application CSS inside the same themed subtree.
+- Keep one real `h1` in `main`. Use `header`, labelled `nav`, `aside`, and `main` landmarks; do not use visual heading styles as a substitute for heading order.
+- Use native anchors for navigation so open-in-new-tab, copy-link, and browser history continue to work. Use buttons for actions.
+- Preserve visible focus, keyboard order, skip navigation, accessible names, and `aria-current="page"`. Ensure sticky content does not obscure focused targets or anchor destinations; use `scroll-margin-block-start` where needed.
+
+Avoid deprecated `Grid`/`Row`/`Col` and `ContentLayout`, hardcoded copies of token values, fixed positioning where sticky works, JavaScript viewport checks for pure layout, styling Ring internals or `data-test`, and product-specific frameworks or portal conventions.