Fix random() CSS value documentation

[ayshgoyl]

Description

Updates the random() CSS function documentation to align with the latest CSS Values & Units specification. Replaces the obsolete element-shared model with the new cache key type system (element, property, and property-index), expands parameter documentation, and adds examples demonstrating the new random value sharing behavior.

Motivation

The existing documentation reflects an outdated version of the specification and no longer describes the current random value sharing model. This update improves accuracy, clarifies how random base values are scoped and shared, and provides practical examples to help developers understand and use the new cache key types correctly.

Additional details

• Replaces all references to the deprecated element-shared keyword.
• Documents the element, property, and property-index cache key types.
• Updates syntax, parameter descriptions, and behavior explanations to match the latest specification.
• Adds examples covering cross-property linking, shorthand index scoping, and cache key sharing behavior.

Related issues and pull requests

Fixes #44502

[hamishwillee]

Thanks @ayshgoyl . @bramus Would you like to give this a technical review?

We will also need an update to https://github.com/mdn/browser-compat-data/blob/main/css/types/random.json in order to reflect the new properties

[github-actions]

Preview URLs (1 page)

• /en-US/docs/Web/CSS/Reference/Values/random

(comment last updated: 2026-06-26 05:22:47)

[bramus]

• Documents the element, property, and property-index cache key types.

These are wrong. The values are element-scoped, property-scoped, and property-index-scoped, as per spec.

If you could fix that upfront, I can take a look later.

[hamishwillee]

It's always three backticks.
The flaw predates you - see line 202.
You need to rever to 3 backticks, move the text on 202 to its own line, and remove the backtics on line 205.

Go though and revert anywhere you added an extra backtick and check how rendering looks.

It is much easier to preview this stuff live using - have you run it locally using npm run start?

[hamishwillee]

PS when you think this is ready for another review, please ping Bramus. I'll look properly at the end when it is technically correct. Thanks!

[github-actions]

[mdn-linter] _{reported by reviewdog 🐶}

Suggested change

	margin: random(property-index, 5px, 30px)
	random(property-index, 5px, 30px)
	random(property-index, 5px, 30px)
	random(property-index, 5px, 30px);
	margin: random(property-index, 5px, 30px) random(property-index, 5px, 30px)
	random(property-index, 5px, 30px) random(property-index, 5px, 30px);

[github-actions]

[mdn-linter] _{reported by reviewdog 🐶}

Suggested change

	#### Automatic behavior
	When the first parameter is omitted, or explicitly set to `auto`, an ident is auto-generated from the property name and position. This behavior can cause some unexpected random base value sharing.
	When the first parameter is omitted, or explicitly set to `auto`, a key is auto-generated from the property name and position index within the value. This behavior can cause some unexpected random base value sharing.
	```css
	.foo {
	#### Automatic behavior When the first parameter is omitted,
	or explicitly set to `auto`,
	a
	key
	is
	auto-generated
	from
	the
	property
	name
	and
	position
	index
	within
	the
	value.
	This
	behavior
	can
	cause
	some
	unexpected
	random
	base
	value
	sharing.
	```css
	.foo {

[github-actions]

[mdn-linter] _{reported by reviewdog 🐶}

Suggested change

	margin: random(property-index, 5px, 40px)
	random(property-index, 5px, 40px)
	random(property-index, 5px, 40px)
	random(property-index, 5px, 40px);
	margin: random(property-index, 5px, 40px) random(property-index, 5px, 40px)
	random(property-index, 5px, 40px) random(property-index, 5px, 40px);

[github-actions]

[markdownlint] _{reported by reviewdog 🐶}
error MD033/no-inline-html Inline HTML [Element: random-value-sharing]