docs: styles, distinguish global vs. project (#289)

* docs: distinguish global styles and project styles Proejct styles first introduced in: #288 When mature, they should become Core Styles. * docs: readme ToC typo --------- Co-authored-by: Jake Rosenberg <[email protected]>
TACC · Sep 5, 2023 · b1ed1f7 · b1ed1f7
1 parent 9cafbf8
commit b1ed1f7
Showing 1 changed file with 55 additions and 16 deletions.
diff --git a/apps/tup-ui/src/styles/README.md b/apps/tup-ui/src/styles/README.md
@@ -7,15 +7,17 @@
 - [Browse Core Styles](#browse-core-styles)
 - [Use Core Styles](#use-core-styles)
 - [Create Core Styles](#create-core-styles)
-- [Use Global Project Styles](#use-global-project-styles)
-- [Create Global Project Styles](#create-global-project-styles)
+- [Use Project Styles](#use-project-styles)
+- [Create Project Styles](#create-project-styles)
+- [Use Global Styles](#use-global-styles)
+- [Create Global Styles](#create-global-styles)
 - [Limit Use of Bootstrap](#limit-use-of-bootstrap)
 
 ## How to Style
 
 1. **Avoid** Global Project styles.
 2. Do use and create [Component Styles](#component-styles).
-3. Do use and create [Core Styles].
+3. Do use and create [Core Styles] or [Project Styles].
 4. Do follow our [CSS Style Guide].
 
 ## Component Styles
@@ -108,31 +110,68 @@ selector {
 
 ## Create [Core Styles]
 
-1. Clone [Core Styles].
+1. Clone/Fork [Core Styles].
 2. Develop component.
-3. Request review.\*
+3. Request review.
 
-<sub>\* You might need to request repository access.</sub>
+## Use Project Styles
 
-## Use Global Project Styles
+For new patterns not mature enough for [Core Styles], create it for one project.
 
-### In `main.css`, Import from Global Project Styles
+### In Component Styles, Import from Project Styles
 
-**`/main.global.css`**
+**`.../SomeComponent.module.css`**
+
+```css
+@import url('../../styles/(.../)something-for-just-one-project-not-global.css');
+```
+
+## Create Project Styles
+
+### In Project Styles, Append to [Core Styles]
+
+**`/libs/*/styles/(.../)some-project-stylesheet.css`**
+
+```css
+:root {
+  /* To overwrite @tacc/core-styles/.../settings/color.css */
+  --some-project-prop: 'value';
+}
+```
+
+### In Project Styles, Extend from [Core Styles]
+
+**`/libs/*/styles/(.../)some-project-stylesheet.css`**
 
 ```css
-@import url('/styles/(.../)something-not-already-available-globally.css');
+@import url('@tacc/core-styles/.../tools/x-truncate.css');
+
+selector {
+  @extend .x-truncate--one-line;
+
+  project: 'styles';
+}
+```
+
+## Use Global Styles
+
+### In `main.css`, Import from Global Styles
+
+**`/main.global.css`\***
+
+```css
+@import url('./styles/(.../)something-not-already-available-globally.css');
 ```
 
 <sub>\* A `main.css` might not exist (because no global project styles exist).</sub>
 
-## Create Global Project Styles
+## Create Global Styles
 
 If you need global styles, then evaluate these options.
 
 ### In Global Styles, Append to [Core Styles]
 
-**`/styles/(.../)some-global-stylesheet.css`**
+**`/apps/tup-ui/styles/(.../)some-global-stylesheet.css`**
 
 ```css
 :root {
@@ -141,21 +180,21 @@ If you need global styles, then evaluate these options.
 }
 ```
 
-### In Global Project Styles, Extend from [Core Styles]
+### In Global Styles, Extend from [Core Styles]
 
-**`/styles/(.../)some-global-stylesheet.css`**
+**`/apps/tup-ui/styles/(.../)some-global-stylesheet.css`**
 
 ```css
 @import url('@tacc/core-styles/.../tools/x-truncate.css');
 
 selector {
   @extend .x-truncate--one-line;
 
-  project: 'styles';
+  global: 'styles';
 }
 ```
 
-### In Global Project Styles, Import from [Core Styles]
+### In Global Styles, Import from [Core Styles]
 
 **`/main.global.css`**