Explain limitations of arbitrary values in bg-size and bg-position class groups in docs

docs/README.md

@@ -26,6 +26,7 @@ twMerge('px-2 py-1 bg-red hover:bg-dark-red', 'p-3 bg-[#B91C1C]')
 -   [What is it for](./what-is-it-for.md)
 -   [When and how to use it](./when-and-how-to-use-it.md)
 -   [Features](./features.md)
+-   [Limitations](./limitations.md)
 -   [Configuration](./configuration.md)
 -   [Recipes](./recipes.md)
 -   [API reference](./api-reference.md)

docs/configuration.md

@@ -250,6 +250,6 @@ const twMerge3 = createTailwindMerge(() => ({  … }), withMagic, withMoreMagic)
 
 Next: [Recipes](./recipes.md)
 
-Previous: [Features](./features.md)
+Previous: [Limitations](./limitations.md)
 
 [Back to overview](./README.md)

docs/features.md

@@ -2,7 +2,7 @@
 
 ## Merging behavior
 
-tailwind-merge is designed to be predictable and intuitive. It follows a set of rules to determine which class wins when there are conflicts. Here is a brief overview of the conflict resolution tailwind-merge can do.
+tailwind-merge is built to be intuitive. It follows a set of rules to determine which class wins when there are conflicts. Here is a brief overview of its conflict resolution.
 
 ### Last conflicting class wins
 
@@ -154,7 +154,7 @@ The initial computations are called lazily on the first call to `twMerge` to pre
 
 ---
 
-Next: [Configuration](./configuration.md)
+Next: [Limitations](./limitations.md)
 
 Previous: [What is it for](./what-is-it-for.md)
 

docs/limitations.md

@@ -0,0 +1,21 @@
+# Limitations
+
+## Don't use classes that look like Tailwind classes but apply different styles
+
+tailwind-merge applies some heuristics to detect the type of a class even if that particular class does not exist in the default Tailwind config. E.g. the class `text-1000xl` does not exist in Tailwind CSS by default but is treated like a `font-size` class in tailwind-merge because it starts with `text-` followed by an optional number and a T-shirt size, like all the other `font-size` classes.
+
+This behavior has the advantage that you're less likely to need to configure tailwind-merge if you're only changing or extending some scales in your Tailwind config. But it also means that tailwind-merge treats classes that look like Tailwind classes as Tailwind classes although they might not be defined in your Tailwind config.
+
+## You need to use label in arbitrary `background-position` and `background-size` classes
+
+tailwind-merge detects the type of class by parsing the class name. When using a class like `bg-[30%_30%]`, tailwind-merge can't know whether the class is a `background-position` or `background-size` class.
+
+Therefore it is necessary to always prepend arbitrary values of `background-position` classes with the label `position:` as in `bg-[position:30%_30%]`. The same applies to `background-size` classes which need to be prepended with `length:`, `size:` or `percentage:`.
+
+---
+
+Next: [Configuration](./configuration.md)
+
+Previous: [Features](./features.md)
+
+[Back to overview](./README.md)