From 5bdd9839a78ecad6da83b778c9369ed8d00ba95b Mon Sep 17 00:00:00 2001
From: Adam Kudrna <adam@adamkudrna.cz>
Date: Wed, 6 Mar 2024 18:15:55 +0100
Subject: [PATCH] Correct the documentation of CSS usage

---
 README.md                         | 12 +++++++-----
 src/docs/getting-started/usage.md | 22 +++++++---------------
 src/index.js                      |  3 ++-
 3 files changed, 16 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index 9a177bf3..fc5c2499 100644
--- a/README.md
+++ b/README.md
@@ -62,14 +62,13 @@ To install React UI in your app:
    />
    ```
 
-3. Load the default theme and the CSS foundation layer:
+3. Load React UI CSS in your app:
 
    <!-- eslint-env browser -->
    <!-- eslint-disable import/no-unresolved -->
 
    ```js
-   import '@react-ui-org/react-ui/src/lib/theme.scss';
-   import '@react-ui-org/react-ui/src/lib/foundation.scss';
+   import '@react-ui-org/react-ui/dist/react-ui.css';
    ```
 
    <!-- eslint-env browser -->
@@ -101,8 +100,11 @@ module.exports = (env, argv) => ({
     alias: {
       // Allow to run react-ui in development mode for easier development.
       '@react-ui-org/react-ui$': argv.mode === 'production'
-        ? '@react-ui-org/react-ui/dist/lib.js'
-        : '@react-ui-org/react-ui/dist/lib.development.js',
+        ? '@react-ui-org/react-ui/dist/react-ui.js'
+        : '@react-ui-org/react-ui/dist/react-ui.development.js',
+      '@react-ui-org/react-ui/dist/react-ui.css': modeArgument === 'production'
+        ? '@react-ui-org/react-ui/dist/react-ui.css'
+        : '@react-ui-org/react-ui/dist/react-ui.development.css',
     },
   },
 });
diff --git a/src/docs/getting-started/usage.md b/src/docs/getting-started/usage.md
index 62d98074..fbeb39b3 100644
--- a/src/docs/getting-started/usage.md
+++ b/src/docs/getting-started/usage.md
@@ -29,21 +29,22 @@ performance).
 ## CSS
 
 React UI honors [ITCSS][itcss] principles to make sure that its CSS code base
-will work and perform well even in large scale. There are three global CSS
-layers:
+will work and perform well even in large scale. There are four CSS layers:
 
 1. **Theme:** a collection of hundreds of CSS custom properties that define the
    look of your app. See [Theming][theming] for more.
 2. **Foundation:** mandatory ground-zero CSS for React UI components. Includes
    global resets and fixes rendering inconsistencies across browsers with
    `normalize.css`. (Not to be confused with the Foundation CSS framework.)
-3. **CSS helpers:** tiny CSS classes that can handle details like
+3. **Components:** React UI components' styles. Components utilize [CSS modules]
+   to avoid class name conflicts and to keep the class names scoped.
+4. **CSS helpers:** tiny CSS classes that can handle details like
    [typography][typography], [spacing][spacing], [colors][colors], etc. Class
    name notation is [inspired by Bootstrap][bootstrap-utilities], so if you are
    familiar with Bootstrap, you will feel at home here.
 
-All layers are written in Sass and compiled to CSS. You can import them in a
-**ready-to-use CSS bundle** like this:
+All layers are written in Sass and compiled to CSS. You can import them all in
+a **ready-to-use CSS bundle** like this:
 
 ```js
 import '@react-ui-org/react-ui/dist/react-ui.css';
@@ -51,13 +52,7 @@ import '@react-ui-org/react-ui/dist/react-ui.css';
 
 ### Sass
 
-Alternatively, you can import the Sass source files directly:
-
-```js
-import '@react-ui-org/react-ui/src/theme.scss';
-import '@react-ui-org/react-ui/src/foundation.scss';
-import '@react-ui-org/react-ui/src/helpers.scss';
-```
+👉 As of now, we don't provide a way to import the Sass files directly.
 
 ## Components
 
@@ -69,9 +64,6 @@ import { Button } from '@react-ui-org/react-ui';
 <Button label="My Button" />
 ```
 
-👉 Thanks to [CSS modules], React UI components have their styles bundled
-together with the component code.
-
 ### Controlled vs. Uncontrolled
 
 While you may find out some components are working for you as uncontrolled, we
diff --git a/src/index.js b/src/index.js
index f6e425b4..44f73d0c 100644
--- a/src/index.js
+++ b/src/index.js
@@ -1,5 +1,6 @@
 // Global definitions
-// These need to be imported here to be placed in the distribution CSS file
+// These need to be imported here to be placed in the distribution CSS file.
+// Component styles are imported in the component files themselves.
 import './theme.scss';
 import './foundation.scss';
 import './helpers.scss';