docs(style): theming and foundation styles

clukhei · clukhei · commit 2e5485c5fed5 · 2024-10-25T16:59:19.000+08:00
diff --git a/.github/workflows/sync-to-gist.yml b/.github/workflows/sync-to-gist.yml
@@ -1,4 +1,4 @@
-name: Sync to Gist
+name: Sync to Lu Khei's Gist
 on:
   push:
     branches:
@@ -15,4 +15,15 @@ jobs:
           with:
             gist_token: ${{ secrets.GIST_TOKEN }}
             gist_id: 425e29332ec837d9ea4bbe90ff8d4a37
-            source_path: src/themes
+            source_path: src/themes
+  CSS-Gist:
+    runs-on: ubuntu-latest
+    steps:
+        - name: Checkout
+          uses: actions/checkout@v4
+        - name: Gist Repo Sync
+          uses: pentatonicfunk/action-gist-repo-sync@v1.8
+          with:
+            gist_token: ${{ secrets.GIST_TOKEN }}
+            gist_id: a31bfc0ea0c2b87d950b125f92835a76
+            source_path: src/css
diff --git a/.storybook/preview.ts b/.storybook/preview.ts
@@ -53,6 +53,7 @@ export const parameters = {
         ["Introduction", "Installation", "Imports"],
         "Usage",
         "Frameworks",
+        "Style",
         "Troubleshooting",
         "Components",
         "Patterns",
diff --git a/docs/FoundationalStyles.md b/docs/FoundationalStyles.md
@@ -0,0 +1,73 @@
+# Foundation
+
+The library also provides styles for SGDS foundation to help users style your application wholistically with SGDS. 
+The styles help to override the default browser's native styles with SGDS. 
+
+These files are distributed as CSS files and are optional to import. These styles do not affect the web components and are not required in the web component.
+However, do note that the CSS styles the light dom and may causes clash of styles if there are other styling libraries (for example, tailwind, bootstrap, sgds v1 and v2 css, etc.) used in your app.
+
+Foundation aspects of SGDS includes: 
+ - typography, 
+ - body `<body>`
+ - paragraphs `<p>`
+ - labels `<label>`
+ - anchor `<a>`
+ - captions `<caption>`
+ - headers `<h1>, <h2>, <h3>, <h4>, <h5>, <h6>`
+ - list `<ol>, <ul>, <li>`
+ - grid system <sgds-badge show>work in progress</sgds-badge>
+
+## Import 
+
+The CSS styles are dependent on the css variable tokens. Import the `themes/day.css` file first before importing the css files. If you required night mode, import `themes/night.css` as well. 
+The colors assigned to elements and class selectors will switch depending on day or night mode.
+
+<strong>JS imports</strong>
+
+```js
+import "@govtechsg/sgds-web-component/themes/day.css"
+//optional: if you are doing night mode 
+import "@govtechsg/sgds-web-component/themes/night.css"
+import "@govtechsg/sgds-web-component/css/sgds.css"
+
+```
+
+<strong>CSS imports</strong>
+
+```css
+@import "@govtechsg/sgds-web-component/themes/day.css";
+/** optional: if you are doing night mode */
+@import "@govtechsg/sgds-web-component/themes/night.css";
+@import "@govtechsg/sgds-web-component/css/sgds.css";
+```
+
+### Cherry pick the styles
+
+`css/sgds.css` contains all the stylings found in the folder `css`. You can also choose to cherry pick the styles you required. For example, `label.css`
+
+<strong>JS imports</strong>
+
+```js
+import "@govtechsg/sgds-web-component/themes/day.css"
+//optional: if you are doing night mode 
+import "@govtechsg/sgds-web-component/themes/night.css"
+import "@govtechsg/sgds-web-component/css/label.css"
+
+```
+
+<strong>CSS imports</strong>
+
+```css
+@import "@govtechsg/sgds-web-component/themes/day.css";
+/** optional: if you are doing night mode */
+@import "@govtechsg/sgds-web-component/themes/night.css";
+@import "@govtechsg/sgds-web-component/css/label.css";
+```
+
+## Source files
+
+<iframe
+  src='https://gist.github.com/clukhei/a31bfc0ea0c2b87d950b125f92835a76.pibb'
+  style="width: 100%; height: 1000px; border: 0;"
+>
+</iframe>
diff --git a/docs/Theming.md b/docs/Theming.md
@@ -1,12 +1,10 @@
-# Stylings
+# Stylings 
 
 ## Global Styles and Theming
 
 Customize the styles at the `:root` level by overriding the values of css tokens defined in file 
 `@govtechsg/sgds-web-component/themes/day.css` file. This file contains the primitive and semantic css tokens. For system level UI changes, we encourage you to make primitive and semantic level style changes at the `:root` rather than component specific changes. 
 
-See all tokens in [github](https://github.com/GovTechSG/sgds-web-component/blob/restructure-v2/src/themes/day.css) 
-
 ```css
 // yourCustomCss.css
 :root {
@@ -21,13 +19,41 @@ import "@govtechsg/sgds-web-component/themes/day.css";
 import "./yourCustomCss.css"
 ```
 
-## Component specific styles
+### root.css
+
+Primitives and semantic values are defined here. These tokens can also be found in `@govtechsg/sgds-web-component/themes` folder.
+
+<iframe
+  src='https://gist.github.com/clukhei/425e29332ec837d9ea4bbe90ff8d4a37.pibb?file=root.css'
+  style="width: 100%; height: 300px; border: 0;"
+>
+</iframe>
+
+### day.css
+
+<iframe
+  src='https://gist.github.com/clukhei/425e29332ec837d9ea4bbe90ff8d4a37.pibb?file=day.css'
+  style="width: 100%; height: 300px; border: 0;"
+>
+</iframe>
+
+### night.css
 
-The styles of components are built in and can be modified via cssparts or css custom properties whenever we specify for such styling modificiations. This information will be specified under API section for each component
+<iframe
+  src='https://gist.github.com/clukhei/425e29332ec837d9ea4bbe90ff8d4a37.pibb?file=night.css'
+  style="width: 100%; height: 300px; border: 0;"
+>
+</iframe>
+
+
+
+## Component specific styles <sgds-badge show>work in progress</sgds-badge>
+
+<!-- The styles of components are built in and can be modified via cssparts or css custom properties whenever we specify for such styling modificiations. This information will be specified under API section for each component
 
 You will require some knowledge of web components and css to do so and the information can be readily available online like mdn web docs for [web components](https://developer.mozilla.org/en-US/docs/Web/Web_Components) and [css](https://developer.mozilla.org/en-US/docs/Web/CSS)
 
-### css custom variable
+### css custom variable <sgds-badge show>work in progress</sgds-badge>
 
 Some components have defined css custom variable for styling of selected aspects of the element in the shadow DOM. See the API table for the available css custom variables
 
@@ -37,7 +63,7 @@ sgds-sidenav {
 }
 ```
 
-### cssparts
+### cssparts <sgds-badge show>work in progress</sgds-badge>
 
 Some components expose cssparts on selected elements of the shadow DOM. See the API table for each component on the css parts exposed.
 
@@ -47,9 +73,6 @@ sgds-footer::part(footer-bottom) {
   font-family: "Times New Roman", Times, serif;
   border: 10px dotted red;
 }
-```
-
+``` -->
 
-## External stylings
 
-Any external stylings done on our web components like positioning needs to be done on your end. You can use [SGDS v2 library](https://designsystem.tech.gov.sg/get-started/)to leverage on the position stylings we provide e.g. ms-auto, flexbox, grids
diff --git a/stories/getting-started/Style/FoundationStyle.mdx b/stories/getting-started/Style/FoundationStyle.mdx
@@ -0,0 +1,6 @@
+import { Meta, Markdown } from "@storybook/blocks";
+import FoundationalStyles from '../../../docs/FoundationalStyles.md?raw';
+
+<Meta title="Style/Foundation" />
+
+<Markdown>{FoundationalStyles}</Markdown>
diff --git a/stories/getting-started/Style/Theming.mdx b/stories/getting-started/Style/Theming.mdx
@@ -0,0 +1,6 @@
+import { Meta, Markdown } from "@storybook/blocks";
+import Theming from '../../../docs/Theming.md?raw';
+
+<Meta title="Style/Theming" />
+
+<Markdown>{Theming}</Markdown>
diff --git a/stories/getting-started/Usage/Stylings.mdx b/stories/getting-started/Usage/Stylings.mdx
