From 5a58a77682ee87e2639b1b98d0efa13e401057a8 Mon Sep 17 00:00:00 2001
From: Jacek Pudysz <jacekpudysz@gmail.com>
Date: Tue, 12 Dec 2023 12:36:46 +0100
Subject: [PATCH] feat: polish the docs

---
 docs/astro.config.mjs                         |  8 +++---
 docs/src/components/Seo.astro                 |  4 +--
 .../for-library-authors.mdx                   |  2 +-
 docs/src/content/docs/other/sponsors.mdx      |  2 +-
 .../content/docs/reference/breakpoints.mdx    |  2 +-
 docs/src/content/docs/reference/errors.mdx    | 19 +++++++++++++
 .../content/docs/reference/media-queries.mdx  | 10 +++----
 docs/src/content/docs/reference/plugins.mdx   |  8 +++---
 .../docs/reference/server-side-rendering.mdx  | 27 +++++++++----------
 docs/src/content/docs/reference/theming.mdx   |  2 +-
 .../docs/reference/unistyles-runtime.mdx      | 14 +++++-----
 .../docs/reference/use-initial-theme.mdx      |  2 +-
 .../src/content/docs/reference/use-styles.mdx |  2 +-
 docs/src/content/docs/reference/variants.mdx  | 21 ++++++++-------
 .../content/docs/reference/web-support.mdx    |  2 +-
 docs/src/content/docs/start/benchmarks.mdx    |  2 +-
 docs/src/pages/index.astro                    |  2 +-
 17 files changed, 74 insertions(+), 55 deletions(-)
 rename docs/src/content/docs/{reference => other}/for-library-authors.mdx (97%)

diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index 3838b020..6902e381 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -114,10 +114,6 @@ export default defineConfig({
                         {
                             label: 'FAQ',
                             link: '/reference/faq/'
-                        },
-                        {
-                            label: 'For library authors',
-                            link: '/reference/for-library-authors/'
                         }
                     ]
                 },
@@ -146,6 +142,10 @@ export default defineConfig({
                 {
                     label: 'Other',
                     items: [
+                        {
+                            label: 'For library authors',
+                            link: '/other/for-library-authors/'
+                        },
                         {
                             label: 'Sponsors',
                             link: 'other/sponsors/'
diff --git a/docs/src/components/Seo.astro b/docs/src/components/Seo.astro
index 2b4b80fa..0419354b 100644
--- a/docs/src/components/Seo.astro
+++ b/docs/src/components/Seo.astro
@@ -14,8 +14,8 @@ type Props = {
 }
 
 const { seo: { title, description, image } } = Astro.props as Props
-const DEFAULT_TITLE_PAGE = 'Unistyles'
-const DEFAULT_DESCRIPTION_PAGE = 'React Native StyleSheet 2.0'
+const DEFAULT_TITLE_PAGE = 'Unistyles 2.0'
+const DEFAULT_DESCRIPTION_PAGE = 'Level up your React Native StyleSheet!'
 const DEFAULT_URL_SITE = 'https://reactnativeunistyles.vercel.app'
 const openGraph = {
     title: title ||DEFAULT_TITLE_PAGE,
diff --git a/docs/src/content/docs/reference/for-library-authors.mdx b/docs/src/content/docs/other/for-library-authors.mdx
similarity index 97%
rename from docs/src/content/docs/reference/for-library-authors.mdx
rename to docs/src/content/docs/other/for-library-authors.mdx
index 91078f87..c85bce46 100644
--- a/docs/src/content/docs/reference/for-library-authors.mdx
+++ b/docs/src/content/docs/other/for-library-authors.mdx
@@ -111,7 +111,7 @@ Without component abstraction, you have the freedom to build one. Unistyles supp
 With its smart architecture, you can maintain the same rendering time as the [core](/start/benchmarks/).
 
 :::tip
-If you need any cool feature to support your UI Kit, please open a discussion.
+If you need any cool feature to support your UI Kit, please open a [discussion](https://github.com/jpudysz/react-native-unistyles/discussions).
 
 I'm happy to help you with your use case!
 :::
diff --git a/docs/src/content/docs/other/sponsors.mdx b/docs/src/content/docs/other/sponsors.mdx
index 922ec531..efb7019a 100644
--- a/docs/src/content/docs/other/sponsors.mdx
+++ b/docs/src/content/docs/other/sponsors.mdx
@@ -41,7 +41,7 @@ Do you want to become a sponsor? Read a guide [for sponsors](/other/for-sponsors
 
 ### Bronze
 
-🥈
+🥉
 
 ### Individuals
 
diff --git a/docs/src/content/docs/reference/breakpoints.mdx b/docs/src/content/docs/reference/breakpoints.mdx
index df2d8bcd..3489e26e 100644
--- a/docs/src/content/docs/reference/breakpoints.mdx
+++ b/docs/src/content/docs/reference/breakpoints.mdx
@@ -173,7 +173,7 @@ import { UnistylesRuntime } from 'react-native-unistyles'
 // check the registered breakpoints
 export const RegisteredBreakpoints = () => (
     <Text>
-        My registered breakpoint are {UnistylesRuntime.breakpoints}
+        My registered breakpoint are {JSON.stringify(UnistylesRuntime.breakpoints)}
     </Text>
 )
 ```
diff --git a/docs/src/content/docs/reference/errors.mdx b/docs/src/content/docs/reference/errors.mdx
index f8ce7613..20d89b13 100644
--- a/docs/src/content/docs/reference/errors.mdx
+++ b/docs/src/content/docs/reference/errors.mdx
@@ -15,7 +15,9 @@ Unistyles will only throw errors when it is used incorrectly.
 
 ### RuntimeUnavailable
 
+:::danger[RuntimeUnavailable]
 *"Unistyles runtime is not available. Make sure you followed the installation instructions"*
+:::
 
 This error will be thrown if you try to use Unistyles before it was initialized. 
 Make sure you followed the installation [setup](/start/setup/).
@@ -24,18 +26,23 @@ Still getting this error? Check [FAQ](/reference/faq/).
 
 ### ThemeNotFound / ThemeNotRegistered
 
+:::danger[ThemeNotFound / ThemeNotRegistered]
 *"You are trying to get a theme that is not registered with UnistylesRegistry"*
 
 and
 
 *"You are trying to set a theme that was not registered with UnistylesRegistry"*
+:::
+
 
 These errors occur when you call `UnistylesRuntime.setTheme` with a theme that has not been registered with `UnistylesRegistry`.
 This situation can arise if you don't use TypeScript. Confirm that all your themes are registered with `UnistylesRegistry.addThemes` before using them.
 
 ### ThemeNotSelected
 
+:::danger[ThemeNotSelected]
 *"Your themes are registered, but you didn't select the initial theme"*
+:::
 
 This error is thrown if you have registered multiple themes but failed to select an initial one.
 
@@ -43,7 +50,9 @@ Follow theming [guide](/reference/theming/) to learn how to select the initial t
 
 ### ThemesCannotBeEmpty
 
+:::danger[ThemesCannotBeEmpty]
 *"You are trying to register empty themes object"*
+:::
 
 This error occurs if you attempt to register an empty themes object with  `UnistylesRegistry.addThemes`.
 
@@ -55,7 +64,9 @@ If you don't want to use themes, simply don't register them.
 
 ### BreakpointsCannotBeEmpty
 
+:::danger[BreakpointsCannotBeEmpty]
 *"You are trying to register empty breakpoints object"*
+:::
 
 This error will be thrown if you try to register empty breakpoints object with `UnistylesRegistry.addBreakpoints`.
 
@@ -63,28 +74,36 @@ Breakpoints are optional, if you don't want to use them, simply don't register t
 
 ### BreakpointsMustStartFromZero
 
+:::danger[BreakpointsMustStartFromZero]
 *"You are trying to register breakpoints that don't start from 0"*
+:::
 
 This error occurs when you attempt to register breakpoints that do not start from 0.
 Begin your first breakpoint with a value of 0 to mimic CSS cascade.
 
 ### InvalidPluginName
 
+:::danger[InvalidPluginName]
 *"Plugin name can't start from reserved prefix __unistyles"*
+:::
 
 This error is thrown if you attempt to register a plugin with a name that begins with the `__unistyles` prefix.
 This prefix is reserved for Unistyles' internal plugins.
 
 ### DuplicatePluginName
 
+:::danger[DuplicatePluginName]
 *"You are trying to register a plugin with a name that is already registered"*
+:::
 
 This error occurs when you attempt to register a plugin with a name that has already been registered.
 Review your list of plugins. Perhaps you included the same plugin twice? Or, maybe a plugin with the same name has already been created by someone from the community?
 
 ### CantRemoveInternalPlugin
 
+:::danger[CantRemoveInternalPlugin]
 *"You are trying to remove an internal unistyles plugin"*
+:::
 
 This error is thrown if you attempt to remove an internal Unistyles plugin.
 Currently, it's not possible to remove internal plugins as they are essential for Unistyles to function properly.
diff --git a/docs/src/content/docs/reference/media-queries.mdx b/docs/src/content/docs/reference/media-queries.mdx
index ca2762c6..3def189a 100644
--- a/docs/src/content/docs/reference/media-queries.mdx
+++ b/docs/src/content/docs/reference/media-queries.mdx
@@ -18,7 +18,7 @@ Media queries provide more power and allow you to style cross-platform apps with
 To use media queries, you need to import the `mq` utility and convert your value to an `object`:
 
 ```diff lang="tsx" /mq/ del="backgroundColor: theme.colors.background,"  ins="backgroundColor: {"
-import { createStyleSheet, mq} from 'react-native-unistyles'
+import { createStyleSheet, mq } from 'react-native-unistyles'
 
 const stylesheet = createStyleSheet(theme => ({
     container: {
@@ -41,7 +41,7 @@ The `mq` utility provides Intellisense for quickly building your media queries.
 You can also combine `width` media queries with `height` media queries:
 
 ```tsx /mq/
-import { createStyleSheet, mq} from 'react-native-unistyles'
+import { createStyleSheet, mq } from 'react-native-unistyles'
 
 const stylesheet = createStyleSheet(theme => ({
     container: {
@@ -60,7 +60,7 @@ const stylesheet = createStyleSheet(theme => ({
 Or use only `height` media queries:
 
 ```tsx /mq/
-import { createStyleSheet, mq} from 'react-native-unistyles'
+import { createStyleSheet, mq } from 'react-native-unistyles'
 
 const stylesheet = createStyleSheet(theme => ({
     container: {
@@ -79,7 +79,7 @@ const stylesheet = createStyleSheet(theme => ({
 You can also reuse your defined [breakpoints](/reference/breakpoints/):
 
 ```tsx /xl/
-import { createStyleSheet, mq} from 'react-native-unistyles'
+import { createStyleSheet, mq } from 'react-native-unistyles'
 
 const stylesheet = createStyleSheet(theme => ({
     container: {
@@ -163,6 +163,6 @@ CSS Media queries is an experimental feature and doesn't support all properties
 It will be moved to stable in Unistyles 3.0.
 :::
 
-With `experimentalCSSMediaQueries` set to `false`, Unsityles will update your styles in the `style` attribute.
+With `experimentalCSSMediaQueries` set to `false`, Unsityles will compute your styles in the JavaScript.
 
 </Seo>
diff --git a/docs/src/content/docs/reference/plugins.mdx b/docs/src/content/docs/reference/plugins.mdx
index ae599cd9..aff2f424 100644
--- a/docs/src/content/docs/reference/plugins.mdx
+++ b/docs/src/content/docs/reference/plugins.mdx
@@ -93,7 +93,7 @@ Your function will be called twice: once for the `container` and once for `text`
 
 ### Register plugins with `UnistylesRegistry`
 
-Once you have your plugin, you need to register it with `UnistylesRegistry`:
+Once you have your plugin, you can register it with `UnistylesRegistry`:
 
 ```tsx /plugins/
 import { UnistylesRegistry } from 'react-native-unistyles'
@@ -111,7 +111,7 @@ UnistylesRegistry
 
 Unistyles offers the option to register plugins at runtime, allowing you to enable them only for specific components.
 
-```tsx /runtime/
+```tsx /UnistylesRuntime.addPlugin/
 import { UnistylesRuntime } from 'react-native-unistyles'
 import { myPlugin } from './myPlugin'
 
@@ -126,7 +126,7 @@ export const EnablePlugin: React.FunctionComponent = () => (
 
 Similarly, you can disable plugins at runtime:
 
-```tsx /runtime/
+```tsx /UnistylesRuntime.removePlugin/
 import { UnistylesRuntime } from 'react-native-unistyles'
 import { myPlugin } from './myPlugin'
 
@@ -142,7 +142,7 @@ export const DisablePlugin: React.FunctionComponent = () => (
 
 You can also check which plugins are enabled at runtime:
 
-```tsx /runtime/
+```tsx /UnistylesRuntime.enabledPlugins/
 import { UnistylesRuntime } from 'react-native-unistyles'
 
 export const GetPlugins: React.FunctionComponent = () => (
diff --git a/docs/src/content/docs/reference/server-side-rendering.mdx b/docs/src/content/docs/reference/server-side-rendering.mdx
index e7d02df5..a0385620 100644
--- a/docs/src/content/docs/reference/server-side-rendering.mdx
+++ b/docs/src/content/docs/reference/server-side-rendering.mdx
@@ -17,24 +17,21 @@ Unistyles can render styles on the server-side, which is useful, for example, fo
 
 You just need to modify the `__document.ts` or `__document.js` file in your project root.
 
-```tsx /UnistylesRegistry/
+```diff lang="tsx"
 export const getInitialProps = async ({ renderPage }) => {
     AppRegistry.registerComponent('Main', () => Main)
 
-    UnistylesRegistry
-        .addBreakpoints({
-            xs: 0,
-            sm: 300,
-            md: 500,
-            lg: 800,
-            xl: 1200
-        })
-        .addThemes({
-            light: theme
-        })
-        .addConfig({
-            experimentalCSSMediaQueries: true
-        })
++    UnistylesRegistry
++        .addBreakpoints({
++            xs: 0,
++            sm: 300,
++            md: 500,
++            lg: 800,
++            xl: 1200
++        })
++        .addThemes({
++            light: theme
++        })
 
     const { getStyleElement } = AppRegistry.getApplication('Main')
     const page = await renderPage()
diff --git a/docs/src/content/docs/reference/theming.mdx b/docs/src/content/docs/reference/theming.mdx
index e069b2a8..ce300dbf 100644
--- a/docs/src/content/docs/reference/theming.mdx
+++ b/docs/src/content/docs/reference/theming.mdx
@@ -192,7 +192,7 @@ import { UnistylesRuntime } from 'react-native-unistyles'
 export const ToggleAdaptiveThemes = () => (
     <Button
         title="Disable adaptive themes"
-        onPress={() => UnistylesRuntime.setAdaptiveThemes(false))}
+        onPress={() => UnistylesRuntime.setAdaptiveThemes(false)}
     />
 )
 ```
diff --git a/docs/src/content/docs/reference/unistyles-runtime.mdx b/docs/src/content/docs/reference/unistyles-runtime.mdx
index 6e066f63..38ba4227 100644
--- a/docs/src/content/docs/reference/unistyles-runtime.mdx
+++ b/docs/src/content/docs/reference/unistyles-runtime.mdx
@@ -14,7 +14,7 @@ import Seo from '../../../components/Seo.astro'
 Unistyles Runtime is the most powerful part of Unistyles 2.0. 
 It replaces much of the functionality previously handled by the React Native API. It also keeps track of your device dimensions, orientation, theme, preferred scheme, etc.
 
-You can interact with Unistyles via `Unistyles Runtime` in your code.
+You can interact with Unistyles via `UnistylesRuntime` in your code.
 
 :::tip
 Unistyles Runtime is a Host Object (created in C++). It's always up to date and allows you to interact with the native side of Unistyles.
@@ -49,8 +49,8 @@ and use it anywhere in your code, even outside a component.
 | ---- | ---- | ----------- |
 | setTheme | (themeName: string) => void | Change the current theme |
 | setAdaptiveThemes | (enabled: boolean) => void | Toggle [adaptive themes](/reference/theming#adaptive-themes) |
-| addPlugin | (plugin: UnistylesPlugin) => void | Enable a plugin |
-| removePlugin | (plugin: UnistylesPlugin) => void | Disable a plugin |
+| addPlugin | (plugin: UnistylesPlugin) => void | Enable a [plugin](/reference/plugins/) |
+| removePlugin | (plugin: UnistylesPlugin) => void | Disable a [plugin](/reference/plugins/) |
 
 ### Why doesn't `UnistylesRuntime` re-render my component?
 
@@ -59,9 +59,11 @@ It's not a React component, so it doesn't re-render your component when, for exa
 
 ### How to re-render my stylesheets based on `UnistylesRuntime`?
 
-If you use `UnistylesRuntime` in your `createStyleSheet` it will automatically re-render your styles to get the perfect styles in real-time.
+If you use `UnistylesRuntime` in your `createStyleSheet` it will automatically re-render your styles to get the correct values in real-time.
 
-One example could be reading device width and height. Using `Dimensions` from React Native won't work as intended, as it will always return the same value.
+One example could be reading device width and height. 
+
+Using `Dimensions` from React Native won't work as intended, as it will always return the same value.
 
 ```tsx /UnistylesRuntime/
 import { UnistylesRuntime, createStyleSheet } from 'react-native-unistyles'
@@ -78,7 +80,7 @@ const stylesheet = createStyleSheet(theme => ({
 ```
 
 :::tip
-Your stylesheets will only be re-rendered on a few changes in Unistyles Runtime:
+Your stylesheets with `UnistylesRuntime` will only be re-rendered when:
 - screen size changes
 - orientation changes
 - breakpoint changes
diff --git a/docs/src/content/docs/reference/use-initial-theme.mdx b/docs/src/content/docs/reference/use-initial-theme.mdx
index 59a4ddbd..618fcc33 100644
--- a/docs/src/content/docs/reference/use-initial-theme.mdx
+++ b/docs/src/content/docs/reference/use-initial-theme.mdx
@@ -11,7 +11,7 @@ import Seo from '../../../components/Seo.astro'
     }}
 >
 
-This hook is optional, but its use is required under certain circumstances, as described in the [theming guide](/referece/theming#select-theme).
+This hook is optional, but its use is required under certain circumstances, as described in the [theming guide](/reference/theming/#select-theme).
 
 If you're using multiple themes and need to determine the initial theme during runtime, this hook is necessary to select the initial theme.
 
diff --git a/docs/src/content/docs/reference/use-styles.mdx b/docs/src/content/docs/reference/use-styles.mdx
index aa3b9ef3..be4a4009 100644
--- a/docs/src/content/docs/reference/use-styles.mdx
+++ b/docs/src/content/docs/reference/use-styles.mdx
@@ -41,7 +41,7 @@ const { theme, breakpoint } = useStyles()
 
 ### Basic usage (stylesheet)
 
-For more advanced usage, pass your `stylesheet` generated with `createStyleSheet`:
+For more advanced usage, pass your `stylesheet` generated with [createStyleSheet](/reference/create-stylesheet/):
 
 ```tsx
 // you can still access theme and current breakpoint
diff --git a/docs/src/content/docs/reference/variants.mdx b/docs/src/content/docs/reference/variants.mdx
index 30da3719..30b2e357 100644
--- a/docs/src/content/docs/reference/variants.mdx
+++ b/docs/src/content/docs/reference/variants.mdx
@@ -11,7 +11,8 @@ import Seo from '../../../components/Seo.astro'
     }}
 >
 
-Variants, the most requested feature in version 1.0, are now available to use with other Unistyles features like media queries and breakpoints!
+Variants were the most requested feature in version 1.0 and are now available to use!
+You can mix them with other Unistyles features like [media queries](/reference/media-queries/) and  d[breakpoints](/reference/breakpoints/).
 
 ## Basic usage
 
@@ -36,9 +37,9 @@ const stylesheet = createStyleSheet(theme => ({
 
 Variants contain `groups` of atomic variants. 
 
-First, you need to name your group and then define variants within it:
+To define a group, first you need to name it and then define variants within it:
 
-```tsx /colors/ /sizes/ /otherGroupName/
+```tsx /color/ /size/ /otherGroupName/
 const stylesheet = createStyleSheet(theme => ({
     container: {
         flex: 1,
@@ -56,7 +57,7 @@ These groups will later be used to select your variants, so remember to name the
 With the given structure, you can now define your variants that can contain any number of styles. You can also use
 `breakpoints`, `media queries` or styles like `transform`:
 
-```tsx /color/ /size/ /otherGroupName/
+```tsx /color:/ /size:/ /otherGroupName:/
 const stylesheet = createStyleSheet(theme => ({
     container: {
         flex: 1,
@@ -144,22 +145,22 @@ const stylesheet = createStyleSheet(theme => ({
 If you pass `undefined` or `empty object` Unsityles will try to find the `default` variant in your stylesheet:
 
 ```tsx /undefined/ /{}/
-const styles = useStyles(stylesheet, undefined) // will use default variant
-const styles = useStyles(stylesheet, {}) // will use default variant
+const { styles } = useStyles(stylesheet, undefined) // will use default variant (if any)
+const { styles } = useStyles(stylesheet, {}) // will use default variant (if any)
 ```
 
 Passing an object with named keys and `undefined` will work the same way dafaulting to the `default` option:
 
 ```tsx /undefined/
-const styles = useStyles(stylesheet, {
-    color: undefined // will use default variant
+const { styles } = useStyles(stylesheet, {
+    color: undefined // will use default variant (if any)
 })
 ```
 
 Lastly, you can pass the correct variant name for a variant group:
 
 ```tsx /secondary/
-const styles = useStyles(stylesheet, {
+const { styles } = useStyles(stylesheet, {
     color: 'secondary' // will use secondary variant
 })
 ```
@@ -189,7 +190,7 @@ type ComponentProps = {
 }
 
 const Component: React.FunctionComponent = ({ color, size }) => {
-    const styles = useStyles(stylesheet, {
+    const { styles } = useStyles(stylesheet, {
         color,
         size
     })
diff --git a/docs/src/content/docs/reference/web-support.mdx b/docs/src/content/docs/reference/web-support.mdx
index 17801586..ac78222c 100644
--- a/docs/src/content/docs/reference/web-support.mdx
+++ b/docs/src/content/docs/reference/web-support.mdx
@@ -11,7 +11,7 @@ import Seo from '../../../components/Seo.astro'
     }}
 >
 
-Unistyles offers first-class support for `React Native Web. 
+Unistyles offers first-class support for `React Native Web`. 
 No additional configuration is needed to use it. Your stylesheets will function identically on both mobile and web platforms.
 
 ### CSS Media Queries
diff --git a/docs/src/content/docs/start/benchmarks.mdx b/docs/src/content/docs/start/benchmarks.mdx
index d42e69ce..0da5650b 100644
--- a/docs/src/content/docs/start/benchmarks.mdx
+++ b/docs/src/content/docs/start/benchmarks.mdx
@@ -24,7 +24,7 @@ import Benchmark5 from '../../../assets/benchmark-5.png'
  It provides low-level functionality for developers who either want full control of styling in their commercial projects or for library authors to build UI Kits on top of it.
 
 
-It's also worth mentioning that there won't be a faster way than passing your objects to StyleSheet.create.
+It's also worth mentioning that there won't be a faster way than passing your objects to `StyleSheet.create`.
 Unfortunately, the functionalities of StyleSheet are limited. Building a fully-featured, cross-platform app without some additional help is challenging.
 
 :::caution
diff --git a/docs/src/pages/index.astro b/docs/src/pages/index.astro
index e3cc7631..95205771 100644
--- a/docs/src/pages/index.astro
+++ b/docs/src/pages/index.astro
@@ -9,7 +9,7 @@ import Seo from '../components/Seo.astro'
 import '../styles/home.css'
 
 const homeSeo = {
-    title: 'Welcome to Unistyles | Unistyles',
+    title: 'Welcome to Unistyles 2.0 | Unistyles',
     description: 'Level up your React Native StyleSheet'
 }
 ---