refactor(styles): introduce nesting stylesheet syntax

.agents/skills/port-gitlab-ui-component/SKILL.md

@@ -69,6 +69,8 @@ Keep stylesheet provenance boundaries strict. A component's colocated CSS may co
 
 When authoring component CSS, prefer `@apply` with supported upstream `gl-*` utilities wherever it preserves the intended declaration and cascade. When upstream already uses `@apply`, keep its utility choices, variant prefixes, grouping, and source order as closely as the local Tailwind build and React structure allow. Keep native CSS for component-specific tokens, Sass-only constructs, compatibility adaptations, missing utilities, or cases where `@apply` would change specificity or source-order behavior. See [references/react-porting.md](references/react-porting.md) for the detailed boundary.
 
+Match the upstream stylesheet's selector organization as closely as the local React and Base UI structure allows. When upstream uses Sass-style nesting, preserve the equivalent nesting for states, modifiers, descendants, combinators, and conditional at-rules; when upstream leaves a rule flat, keep its local counterpart flat instead of introducing nesting merely because the build supports it. Nest only when the existing `postcss-nested` pipeline expands to the same selector set, specificity, at-rule context, and source order. Do not introduce Sass variables, mixins, loops, or interpolation.
+
 If upstream behavior cannot be supported without a missing local primitive, either add the smallest reusable prerequisite within scope or preserve a clear typed API boundary and document the deliberate deferral. Never silently drop a supported state.
 
 ### 4. Verify in increasing cost order

.agents/skills/port-gitlab-ui-component/references/react-porting.md

@@ -29,10 +29,13 @@ Use this reference after the upstream compatibility checklist is known. It captu
 - Model closed variants with `cva` and exported literal unions. Keep structural classes separate from consumer `className` merging.
 - Treat upstream stylesheet boundaries as part of the port. Colocated component CSS may contain only rules whose semantic source is the corresponding upstream component stylesheet, including declarations generated by mixins, utilities, or required build-compatibility transforms invoked there. Rules supplied transitively by Bootstrap, vendor/global styles, or imported stylesheets belong in the matching shared styles layer, scoped to a component marker where needed and imported before component-private CSS.
 - Translate Sass into colocated CSS and prefer `@apply` with supported `gl-*` utilities whenever they express the same semantics.
+- Treat the upstream nesting structure as part of the stylesheet organization. Mirror equivalent Sass-style nesting for pseudo-classes, pseudo-elements, modifiers, suffixes, descendants, combinators, and nested `@media`, `@supports`, or `@container` rules when the local selectors correspond directly. If upstream keeps a rule flat, keep the local counterpart flat; nesting support alone is not a reason to reorganize it.
+- Before nesting selector lists or sharing a parent rule, confirm that expansion produces exactly the intended selector set. The compiled result must preserve selector specificity, declarations, at-rule context, relative source order, and cascade. If React or Base UI adaptation breaks the one-to-one structure, prefer the clearest semantically equivalent local organization and record meaningful deviations.
+- Use only Sass-style nesting syntax supported by the existing `postcss-nested` pipeline. Keep Sass variables, mixins, loops, and interpolation expanded into supported CSS rather than introducing a new preprocessing capability.
 - When upstream already uses `@apply`, preserve the same utility candidates, variant prefixes, grouping, and source order wherever practical instead of rewriting them into merely equivalent utilities. Deviate only when required by unsupported local utilities or configuration, React or Base UI structure, or cascade and specificity constraints; record meaningful deviations.
 - Use the same `@apply` approach for exact utility equivalents introduced by React or Base UI adaptations.
 - Keep native CSS declarations for component-specific tokens, Sass variables/calculations/mixins after expansion, literal values without a meaningful utility, and cases where `@apply` would change cascade, specificity, or source-order behavior. Keep transitive global-style compensation in the appropriate shared layer rather than a component's colocated stylesheet. Do not invent arbitrary utilities merely to eliminate native declarations.
-- Component source may contain `@apply`, but the published styles output must contain only compiled CSS. Verify that the styles package build expands every directive and regenerate `packages/styles/dist` rather than editing it directly.
+- Component source may contain `@apply` and supported nesting, but the published styles output must contain only fully expanded CSS. Verify that the styles package build expands every directive and nested rule, and regenerate `packages/styles/dist` rather than editing it directly.
 - Inspect mixin definitions and transitive global styles before replacing them; do not approximate a hidden behavior by appearance alone.
 - Cover hover, active, focus-visible, disabled, dark theme, forced colors, reduced motion, and responsive behavior only where upstream or shared foundations support them.
 - Import component CSS from `packages/styles/src/components.css`. Regenerate `packages/styles/dist` with the styles package build; never hand-edit generated output.