v4.0.0

[4.0.0] – 2026-04-20

Why This Is A Major Release

browserux.css started as a single-file CSS foundation. With 4.0.0, it becomes a more structured product: modular public bundles, an explicit build pipeline, stronger contribution guidance, and the start of an automated multi-browser validation workflow.

The historical root entry is still preserved for compatibility, but the package surface, release workflow, and maintenance model are now materially broader than in 3.x. This version signals that architectural shift clearly and marks the transition from "one CSS file" to "a maintained CSS foundation with modular distribution and validation tooling".

Foundation And Behavior Changes

• Focus fallback strategy
  Replaced the global :focus { outline: none; } reset with a safer progressive-enhancement pattern: :focus now provides a visible fallback outline, :focus:not(:focus-visible) removes it after mouse interaction in supporting browsers, and :focus-visible keeps the branded keyboard focus ring. This preserves visible focus in browsers that do not support :focus-visible while keeping the intended UX in modern browsers.

• [hidden] compatibility with hidden="until-found"
  Refined the defensive hidden rule from a blanket [hidden] { display: none !important; } to [hidden]:where(:not([hidden="until-found"])) { display: none !important; }. This keeps the classic hidden state protected against accidental overrides while preserving the browser's native "hidden until found" behavior for in-page search and fragment navigation.

• Removed global overscroll-behavior: contain from html
overscroll-behavior remains a useful technique for preventing scroll chaining, but applying it at the page level also changes native browser behaviors such as pull-to-refresh and gesture navigation in some environments. The rule has been removed from the global foundation and is now better understood as a targeted component-level technique.

Distribution And Tooling

• Modular distribution architecture
  Introduced internal src/modules/ and src/entries/ layers plus new public bundles in dist/ (core.css, a11y.css, browser-ui.css, browserux.layer.css). The historical root browserux.css file remains the primary public entry point so existing users can keep importing the package exactly as before while advanced users gain finer control.

• Build pipeline for modular releases
  Added npm run build to regenerate the public bundles in dist/ from src/entries/ and keep the root browserux.css file synchronized with the generated full bundle.

• Playwright validation skeleton
  Added a Playwright foundation with Chromium, Firefox, and WebKit projects, demo helpers, smoke tests, and npm scripts for future automated browser validation.

• First real automated scenario
  Added the first high-priority Playwright scenario for focus-visible, validating pointer vs keyboard focus behavior on the demo across Chromium, Firefox, and WebKit.

• Additional real automated scenarios
  Added four more high-priority Playwright scenarios for :user-valid / :user-invalid, @starting-style on dialog, scrollbar-gutter: stable, and color-scheme: light dark. These tests now validate the corresponding demo contracts across Chromium, Firefox, and WebKit using DOM and computed-style assertions that match each engine's observable behavior.

Experimentation And Research

• CSS lab workspace (lab/browserux.lab.css)
  Introduced an internal lab sheet to track promising CSS features that align with the BrowserUX philosophy but are not yet mature enough to ship in the foundation. Each entry documents what the feature does, its current status (watching, trial, ready-soon, migrated, rejected), why it matters for BrowserUX, and the conditions under which it can migrate into browserux.css. The lab file is never distributed via npm or the CDN and stays a working document, with a dedicated lab/README.md describing the workflow.

Documentation And Developer Experience

• Updated the focus documentation to explain the new fallback strategy and why it is safer for a published CSS foundation.
• Expanded the [hidden] reference to explain why hidden="until-found" must be excluded from the defensive reset, in line with the project's learning-oriented role.
• Updated the default styles reference to explain why overscroll-behavior is no longer applied globally and when it should be used intentionally instead.
• Added documentation for the new modular bundle architecture, public import paths, and bundle responsibilities.
• Added a dedicated guide for integrating browserux.layer.css with CSS Cascade Layers.
• Reworked the browser support guide to separate baseline support, progressive enhancements, and limited-support features for a clearer compatibility story.
• Replaced floating GitHub CDN examples with version-pinned npm CDN URLs in the documentation to make installs more reproducible.
• Expanded the comparison guide to include sanitize.css, classless frameworks such as Pico CSS and Water.css, and complementary tools such as Open Props.
• Added a short decision guide to help users choose between browserux.css, other CSS foundations, and the BrowserUX public bundles.
• Added stack-specific integration recipes for plain HTML, Vite, React, Vue, Astro, and Next.js.
• Clarified the distinction between the neutral foundation layers and the more opinionated BrowserUX layer across the modular bundle documentation.
• Structured contribution guidance with a root CONTRIBUTING.md, a clearer contribution workflow, and GitHub issue and pull request templates.
• Added a demo validation matrix to map BrowserUX features to stable demo targets, verification styles, and automation priorities.
• Added a Playwright setup guide covering dependency installation, browser installation, base URL usage, and the initial local validation workflow.
• Reworked the inline comments across browserux.css and the modular sources using the front-comments Claude Code skill (Effeilo/claude-code-frontend-skills) for consistent structure, clearer intent, and uniform formatting.

v3.0.0

[3.0.0] – 2026-03-26

✨ Added

Browser adaptation

• color-scheme: light dark on :root
  Instructs the browser to apply its native light/dark defaults for UI elements (scrollbars, form controls, etc.), even before any CSS is parsed.

• interpolate-size: allow-keywords on :root
  Enables CSS transitions to and from intrinsic size keywords (auto, min-content, max-content, fit-content) across the entire document. Unlocks native height animations without JavaScript.

• scrollbar-gutter: stable on html
  Reserves space for the scrollbar gutter even when no scrollbar is shown, preventing layout shifts between pages with and without overflow. Works alongside overflow-y: scroll as a fallback.

• overscroll-behavior: contain on html
  Prevents scroll chaining: when a scrollable area reaches its boundary, the viewport no longer scrolls. contain preserves the native elastic/bounce effect on the element itself.

New media query support

• @media (prefers-reduced-transparency: reduce)
  Reduces transparency for users who prefer it. The dialog::backdrop becomes near-opaque (rgba(0,0,0,0.9)) and the scrollbar background aligns with the page color.

• @media (forced-colors: active)
  Windows High Contrast Mode support. Restores the focus ring using the system Highlight color, adds a visible border on form elements whose border was removed by the reset, and applies opacity: 0.5 on disabled elements.

Element normalization

• Headings (h1–h6)
  Added text-wrap: balance for improved typographic readability, especially on narrow viewports.

• Horizontal rule (hr)
  Replaces the browser-default 3D border with a clean, theme-consistent separator using border-top: 1px solid currentColor.

• Fieldset & Legend (fieldset, legend)
  Removes the default browser border and padding on fieldset, and the internal padding on legend, providing a clean form grouping container.

• Dialog (dialog, dialog::backdrop)
  Normalizes dialog with theme variables and adds a native entry animation using @starting-style (fade + slide) wrapped in @media (prefers-reduced-motion: no-preference). The allow-discrete transition on display and overlay ensures the animation completes before the element is hidden.

• [hidden] semantic fix
  Adds display: none !important to [hidden] so elements marked as hidden are never accidentally revealed by other CSS rules.

• Print styles (@media print)
  Added a dedicated print section that removes backgrounds, box shadows, and decorative colors, and shows full URLs after links.

Form UX

• field-sizing: content on textarea
  The textarea automatically resizes to fit its content, eliminating the need for JavaScript auto-resize solutions. resize: vertical is kept as a fallback for unsupported browsers.

• caret-color: var(--bux-color-primary) on input, textarea, [contenteditable]
  Applies the theme's primary color to the text insertion cursor for consistent visual theming.

Typography

• text-underline-offset: 0.2em on a
  Moves the underline slightly below the text baseline, reducing collisions with descenders and improving legibility.

Dark mode

• Three missing variable overrides added to @media (prefers-color-scheme: dark):
  • --bux-valid-bg-color: #0d2e18
  • --bux-invalid-bg-color: #2e0d0d
  • --bux-scrollbar-track: #1a2535

🔧 Changed

• Smooth theme transition moved into @media (prefers-reduced-motion: no-preference)
  The body { transition } rule now only applies when the user has not opted for reduced motion, correctly respecting their preference.

• Field validation states now use :user-valid / :user-invalid instead of :valid / :invalid
  These pseudo-classes only activate after the user has interacted with the field, preventing premature error styling on page load.

• Disabled elements ([disabled], [aria-disabled="true"])
  Added cursor: not-allowed to clearly communicate that an element is non-interactive.

• Body now includes overflow-wrap: break-word
  Prevents long words or URLs from overflowing their container, particularly useful on narrow viewports.

• overflow-y: scroll and scrollbar-gutter: stable on html
  Comments updated to explicitly document their complementary roles: scrollbar-gutter: stable is the modern solution; overflow-y: scroll is kept as a fallback for browsers that do not yet support it. Both are required for full cross-browser coverage.

• ::-moz-progress-bar now correctly uses var(--bux-progress-value-bg) instead of var(--bux-progress-bar-bg).
  In Firefox, ::-moz-progress-bar targets the filled portion of the progress bar (the value), not the track. The wrong variable was applied since v1.0.1.

• Inconsistent indentation fixed throughout browserux.css.
  Several rules were using tabs instead of 2-space indentation, inconsistent with the rest of the file. All properties are now uniformly indented with 2 spaces.

➖ Removed

• details, summary { accent-color }
accent-color has no effect on <details> and <summary> elements in any browser. The rule was a no-op and has been removed. For custom summary marker styling, use summary::marker or a ::before pseudo-element.

• ol, ul { list-style: none }
  Removing list markers globally is too opinionated for a base stylesheet and can degrade accessibility (VoiceOver removes list semantics when list-style: none is applied without role="list"). Apply this reset selectively in your own stylesheet where needed.

✅ Fixed

• @media (prefers-contrast: more) in dark mode
  Added a combined @media (prefers-contrast: more) and (prefers-color-scheme: dark) block. The near-black placeholder and disabled-element colors defined in the base contrast block were invisible against the dark background. They are now overridden with near-white values (rgba(239, 239, 239, 0.9)) when both preferences are active simultaneously.

v2.0.0

[2.0.0] – 06-06-2025

💥 Breaking change

CSS variable prefix update:

To improve project scalability and avoid naming collisions with other libraries or design systems, all CSS variables previously prefixed with --ui- have been renamed to --bux-.

This change clarifies the scope of the BrowserUX design system (Bux) and prepares for better integration into multi-source projects.

Example:

- --ui-color-primary
+ --bux-color-primary

Required action for users:

• If you override CSS variables in your own stylesheets, rename them using the --bux- prefix
• If you use a theme or token system based on --ui-, consider migrating it to --bux-

Tip : You can temporarily add manual aliases to ensure a smooth transition:

:root {
  --ui-color-primary: var(--bux-color-primary);
  --ui-spacing-small: var(--bux-spacing-small);
}

🔧 v1.0.2 – Minor fixes and cleanup

This release includes small but important maintenance updates to improve the quality and clarity of the codebase.

✨ Changes
✅ Removed hardcoded color values from the dark mode section
→ Now all dark mode styles rely on CSS variables only

✅ Fixed inconsistent indentation in browserux.css
→ For better readability and consistency

✅ Corrected inaccurate or misleading comments in the CSS file