@jetbrains/ring-ui 7.0.121 → 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/components/collapse/collapse-content.d.ts

@@ -1,5 +1,12 @@
 import React, { type PropsWithChildren } from 'react';
 interface Props {
+    /**
+     * Height of the always-visible preview of the collapsed content.
+     * The collapsed subtree is inert until expanded, matching `aria-expanded`.
+     * The preview is only a visual clip of that subtree, so it is inert too and
+     * assistive technology will not perceive it — if the preview carries essential
+     * information, expose an accessible summary outside the collapsed content.
+     */
     minHeight?: number;
     className?: string;
     'data-test'?: string | null | undefined;

package/components/collapse/collapse-content.js

@@ -10,11 +10,21 @@ const DURATION_FACTOR = 0.5;
 const DEFAULT_HEIGHT = 0;
 const VISIBLE = 1;
 const HIDDEN = 0;
+// margin for the hide fallback timer, so it fires only if transitionend never did
+const HIDE_FALLBACK_EXTRA_DELAY = 100;
+// React 18 renders unknown attributes from strings only, while React 19 treats `inert`
+// as a real boolean and removes the attribute when it gets ''
+// TODO drop the React 18 branch in develop-8.0 — Ring UI 8.0 supports React 19 only
+const REACT_MAJOR_WITH_INERT_SUPPORT = 19;
+const getInertAttributeValue = (reactMajor) => reactMajor >= REACT_MAJOR_WITH_INERT_SUPPORT ? true : '';
+// the cast is confined to the JSX assignment: React 18 actually receives the string form
+const INERT = getInertAttributeValue(Number(React.version.split('.')[0]));
+const isFullyCollapsed = (collapsed, initialContentHeight) => collapsed && initialContentHeight <= DEFAULT_HEIGHT;
 /**
  * @name CollapseContent
  */
 export const CollapseContent = ({ children, minHeight = DEFAULT_HEIGHT, 'data-test': dataTest, }) => {
-    const { collapsed, duration, id, disableAnimation } = useContext(CollapseContext);
+    const { collapsed, duration, id, disableAnimation, keepMounted } = useContext(CollapseContext);
     const containerRef = useRef(null);
     const contentRef = useRef(null);
     const [initialContentHeight] = useState(minHeight);
@@ -23,20 +33,42 @@ export const CollapseContent = ({ children, minHeight = DEFAULT_HEIGHT, 'data-te
     const height = toPx(nextHeight);
     const [shouldHideContent, setShouldHideContent] = useState(collapsed && minHeight <= DEFAULT_HEIGHT);
     useEffect(() => {
-        function onTransitionEnd() {
+        const container = containerRef.current;
+        function finalizeCollapse() {
             if (initialContentHeight <= DEFAULT_HEIGHT) {
                 setShouldHideContent(collapsed);
             }
         }
-        const container = containerRef.current;
+        function onTransitionEnd(event) {
+            // transitionend bubbles: only the container's own height transition finalizes the collapse
+            if (event.target === container && event.propertyName === 'height') {
+                finalizeCollapse();
+            }
+        }
         container?.addEventListener('transitionend', onTransitionEnd);
+        // fallback for suppressed or cancelled transitions (e.g. `transition: none` overrides),
+        // which emit no transitionend and would otherwise leave the content interactive forever.
+        // Armed once per collapse toggle from the --duration committed to the DOM — the value
+        // the running transition actually uses — so it can neither undercut a transition started
+        // from a stale height nor be restarted by content resizes or duration changes mid-collapse
+        // TODO merge with global/parse-css-duration when this lands in develop-8.0
+        const cssDuration = parseFloat(container?.style.getPropertyValue('--duration') || '') || 0;
+        const fallbackTimeout = window.setTimeout(finalizeCollapse, cssDuration + HIDE_FALLBACK_EXTRA_DELAY);
         return () => {
             container?.removeEventListener('transitionend', onTransitionEnd);
+            window.clearTimeout(fallbackTimeout);
         };
     }, [collapsed, initialContentHeight]);
+    // render-phase state adjustments (not effects): the React Compiler lint forbids
+    // setState-in-effect, and https://react.dev/learn/you-might-not-need-an-effect
+    // documents this pattern for resetting state when props change
     if (!collapsed && shouldHideContent) {
         setShouldHideContent(false);
     }
+    // without a transition there is no transitionend to wait for, so hide immediately
+    if (disableAnimation && !shouldHideContent && isFullyCollapsed(collapsed, initialContentHeight)) {
+        setShouldHideContent(true);
+    }
     useEffect(() => {
         if (contentRef.current) {
             const observer = new ResizeObserver(() => {
@@ -52,10 +84,20 @@ export const CollapseContent = ({ children, minHeight = DEFAULT_HEIGHT, 'data-te
         opacity: collapsed && !minHeight ? HIDDEN : VISIBLE,
     };
     const fadeShouldBeVisible = Boolean(minHeight && collapsed);
-    const shouldRenderContent = disableAnimation ? !collapsed : !shouldHideContent;
+    const contentVisible = !shouldHideContent;
+    const contentHidden = Boolean(keepMounted) && !contentVisible;
+    // interaction is blocked as soon as the panel collapses (matching aria-expanded), while
+    // visibility waits for the animation to finish so the content stays painted meanwhile.
+    // This includes a minHeight preview: content clipped below it must not take focus,
+    // and inert cannot be applied any more granularly than to the whole subtree
+    const contentInert = collapsed;
     return (<div ref={containerRef} id={`collapse-content-${id}`} data-test={dataTests(COLLAPSE_CONTENT_CONTAINER_TEST_ID)} className={classNames(styles.container, { [styles.transition]: !disableAnimation })} style={style}>
-      <div ref={contentRef} data-test={dataTests(COLLAPSE_CONTENT_TEST_ID, dataTest)}>
-        {shouldRenderContent ? children : null}
+      <div ref={contentRef} data-test={dataTests(COLLAPSE_CONTENT_TEST_ID, dataTest)} 
+    // visibility: hidden removes the fully collapsed content from the tab order and accessibility
+    // tree, but descendants can override it with visibility: visible — inert cannot be escaped.
+    // Both are rendered in JSX so server-rendered collapsed markup is protected before hydration.
+    style={contentHidden ? { visibility: 'hidden' } : undefined} inert={contentInert ? INERT : undefined}>
+        {keepMounted || contentVisible ? children : null}
       </div>
       {fadeShouldBeVisible && <div className={styles.fade}/>}
     </div>);

package/components/collapse/collapse-context.d.ts

@@ -2,6 +2,7 @@ interface CollapseContextInterface {
     collapsed: boolean;
     duration: number;
     disableAnimation: boolean;
+    keepMounted?: boolean;
     setCollapsed: () => void;
     id: string;
 }

package/components/collapse/collapse-context.js

@@ -4,6 +4,7 @@ export const CollapseContext = createContext({
     collapsed: true,
     duration: BASE_ANIMATION_DURATION,
     disableAnimation: false,
+    keepMounted: false,
     setCollapsed: () => { },
     id: '',
 });

package/components/collapse/collapse.d.ts

@@ -4,6 +4,15 @@ interface Props {
     onChange?: (collapsed: boolean) => void;
     duration?: number;
     disableAnimation?: boolean;
+    /**
+     * Keep children mounted while collapsed (hidden via `visibility: hidden`
+     * and the `inert` attribute) instead of unmounting them, preserving their state.
+     * Note: hidden form controls still participate in form validation
+     * and submission — disable them while collapsed if needed.
+     * Content rendered through portals (e.g. Popup) escapes the hidden
+     * wrapper and is not hidden — close overlays on collapse.
+     */
+    keepMounted?: boolean;
     className?: string;
     defaultCollapsed?: boolean;
     collapsed?: boolean | null;

package/components/collapse/collapse.js

@@ -5,7 +5,7 @@ import { BASE_ANIMATION_DURATION } from './consts';
 /**
  * @name Collapse
  */
-export const Collapse = ({ children, duration = BASE_ANIMATION_DURATION, disableAnimation = false, className = '', onChange = () => { }, defaultCollapsed = true, collapsed = null, }) => {
+export const Collapse = ({ children, duration = BASE_ANIMATION_DURATION, disableAnimation = false, keepMounted = false, className = '', onChange = () => { }, defaultCollapsed = true, collapsed = null, }) => {
     const [innerCollapsed, setInnerCollapsed] = useState(defaultCollapsed);
     const id = useId();
     const finalCollapsedValue = collapsed ?? innerCollapsed;
@@ -19,6 +19,7 @@ export const Collapse = ({ children, duration = BASE_ANIMATION_DURATION, disable
             setCollapsed,
             duration,
             disableAnimation,
+            keepMounted,
             id,
         }}>
         {children}

package/components/collapsible-group/collapsible-group.css

@@ -37,6 +37,12 @@
   height: 28px;
 }
 
+.heading {
+  margin: 0;
+
+  font: inherit;
+}
+
 .headerButton {
   display: block;
 

package/components/collapsible-group/collapsible-group.d.ts

@@ -10,6 +10,19 @@ export interface CollapsibleGroupProps {
     onChange?: (expanded: boolean) => void;
     disableAnimation?: boolean;
     interactive?: boolean;
+    /**
+     * Keep children mounted while collapsed (hidden via `visibility: hidden`
+     * and the `inert` attribute) instead of unmounting them, preserving their state.
+     * Note: hidden form controls still participate in form validation
+     * and submission — disable them while collapsed if needed.
+     * Content rendered through portals (e.g. Popup) escapes the hidden
+     * wrapper and is not hidden — close overlays on collapse.
+     */
+    keepMounted?: boolean;
+    /**
+     * Wraps the header in an <h2>–<h6> to keep the document outline.
+     */
+    headingLevel?: 2 | 3 | 4 | 5 | 6;
     'data-test'?: string | null | undefined;
 }
 declare const CollapsibleGroup: React.ForwardRefExoticComponent<CollapsibleGroupProps & React.RefAttributes<HTMLDivElement>>;

package/components/collapsible-group/collapsible-group.js

@@ -36,7 +36,7 @@ function CollapsibleGroupHeaderStatic({ avatar, titleContent, subtitle }) {
       <CollapsibleGroupHeaderContent avatar={avatar} titleContent={titleContent} subtitle={subtitle}/>
     </span>);
 }
-const CollapsibleGroup = forwardRef(({ avatar, title, subtitle, children, className, defaultExpanded = false, expanded = null, onChange = () => { }, disableAnimation = false, interactive = true, 'data-test': dataTest, }, ref) => {
+const CollapsibleGroup = forwardRef(({ avatar, title, subtitle, children, className, defaultExpanded = false, expanded = null, onChange = () => { }, disableAnimation = false, interactive = true, keepMounted = false, headingLevel, 'data-test': dataTest, }, ref) => {
     const [innerExpanded, setInnerExpanded] = useState(defaultExpanded);
     const [hovered, setHovered] = useState(false);
     const [focused, setFocused] = useState(false);
@@ -60,9 +60,10 @@ const CollapsibleGroup = forwardRef(({ avatar, title, subtitle, children, classN
         [styles.expanded]: isExpanded,
         [styles.focused]: focused,
     });
+    const header = interactive ? (<CollapsibleGroupHeader avatar={avatar} titleContent={title} subtitle={subtitle} onMouseEnter={() => setHovered(true)} onMouseLeave={() => setHovered(false)} onFocus={() => setFocused(true)} onBlur={onBlur}/>) : (<CollapsibleGroupHeaderStatic avatar={avatar} titleContent={title} subtitle={subtitle}/>);
     return (<div ref={ref} className={classes} data-test={dataTest}>
-        <Collapse defaultCollapsed={!defaultExpanded} collapsed={expanded == null ? null : !expanded} onChange={handleChange} disableAnimation={disableAnimation} className={styles.collapseRoot}>
-          {interactive ? (<CollapsibleGroupHeader avatar={avatar} titleContent={title} subtitle={subtitle} onMouseEnter={() => setHovered(true)} onMouseLeave={() => setHovered(false)} onFocus={() => setFocused(true)} onBlur={onBlur}/>) : (<CollapsibleGroupHeaderStatic avatar={avatar} titleContent={title} subtitle={subtitle}/>)}
+        <Collapse defaultCollapsed={!defaultExpanded} collapsed={expanded == null ? null : !expanded} onChange={handleChange} disableAnimation={disableAnimation} keepMounted={keepMounted} className={styles.collapseRoot}>
+          {headingLevel != null ? React.createElement(`h${headingLevel}`, { className: styles.heading }, header) : header}
           <CollapseContent>
             <div className={styles.body}>{children}</div>
           </CollapseContent>

package/components/expand/collapsible-group.css

@@ -27,6 +27,10 @@
   composes: header from '../collapsible-group/collapsible-group.css';
 }
 
+.heading {
+  composes: heading from '../collapsible-group/collapsible-group.css';
+}
+
 .headerButton {
   composes: headerButton from '../collapsible-group/collapsible-group.css';
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jetbrains/ring-ui",
-  "version": "7.0.121",
+  "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.