From 2e5485c5fed593724bf8d028a250c82ad1322400 Mon Sep 17 00:00:00 2001 From: Lu Khei Chong Date: Fri, 25 Oct 2024 16:59:19 +0800 Subject: [PATCH] docs(style): theming and foundation styles --- .github/workflows/sync-to-gist.yml | 15 +++- .storybook/preview.ts | 1 + docs/FoundationalStyles.md | 73 +++++++++++++++++++ docs/{Stylings.md => Theming.md} | 45 +++++++++--- .../getting-started/Style/FoundationStyle.mdx | 6 ++ stories/getting-started/Style/Theming.mdx | 6 ++ stories/getting-started/Usage/Stylings.mdx | 6 -- 7 files changed, 133 insertions(+), 19 deletions(-) create mode 100644 docs/FoundationalStyles.md rename docs/{Stylings.md => Theming.md} (56%) create mode 100644 stories/getting-started/Style/FoundationStyle.mdx create mode 100644 stories/getting-started/Style/Theming.mdx delete mode 100644 stories/getting-started/Usage/Stylings.mdx diff --git a/.github/workflows/sync-to-gist.yml b/.github/workflows/sync-to-gist.yml index b9a117b2..98367762 100644 --- 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 \ No newline at end of file + 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 \ No newline at end of file diff --git a/.storybook/preview.ts b/.storybook/preview.ts index 2b2b53b2..336d39da 100644 --- 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 new file mode 100644 index 00000000..1248d4d9 --- /dev/null +++ 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 `` + - paragraphs `

` + - labels `

,

,

,

,

,
` + - list `
    ,
      ,
    • ` + - grid system work in progress + +## 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. + +JS imports + +```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" + +``` + +CSS imports + +```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` + +JS imports + +```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" + +``` + +CSS imports + +```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 + + \ No newline at end of file diff --git a/docs/Stylings.md b/docs/Theming.md similarity index 56% rename from docs/Stylings.md rename to docs/Theming.md index c350d9db..93a1555c 100644 --- a/docs/Stylings.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. + + + +### day.css + + + +### 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 + + + + +## Component specific styles work in progress + + -## 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 new file mode 100644 index 00000000..2e2d483a --- /dev/null +++ b/stories/getting-started/Style/FoundationStyle.mdx @@ -0,0 +1,6 @@ +import { Meta, Markdown } from "@storybook/blocks"; +import FoundationalStyles from '../../../docs/FoundationalStyles.md?raw'; + + + +{FoundationalStyles} \ No newline at end of file diff --git a/stories/getting-started/Style/Theming.mdx b/stories/getting-started/Style/Theming.mdx new file mode 100644 index 00000000..5895c874 --- /dev/null +++ b/stories/getting-started/Style/Theming.mdx @@ -0,0 +1,6 @@ +import { Meta, Markdown } from "@storybook/blocks"; +import Theming from '../../../docs/Theming.md?raw'; + + + +{Theming} \ No newline at end of file diff --git a/stories/getting-started/Usage/Stylings.mdx b/stories/getting-started/Usage/Stylings.mdx deleted file mode 100644 index 72282438..00000000 --- a/stories/getting-started/Usage/Stylings.mdx +++ /dev/null @@ -1,6 +0,0 @@ -import { Meta, Markdown } from "@storybook/blocks"; -import Stylings from '../../../docs/Stylings.md?raw'; - - - -{Stylings} \ No newline at end of file