Storybook upgrade (#230)

This PR introduces some changes to the documentation. It does not change the released scss package.

 Update package manager to use modern yarn.
 Updating to the latest Storybook 8.1.3
 Use Vite for compilation instead of Webpack
 Remove React as a direct dev dependency
 Simplify the left sidebar by only showing the documentation pages instead of all the "stories"
 Add links to source code from relevant documentation pages
 Update the Table of Contents to read a bit better.
 Update the side bar styles to be a bit nicer.

.editorconfig

@@ -0,0 +1,10 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+
+[*.{js,json,yml}]
+charset = utf-8
+indent_style = space
+indent_size = 2

.gitattributes

@@ -0,0 +1,4 @@
+/.yarn/**            linguist-vendored
+/.yarn/releases/*    binary
+/.yarn/plugins/**/*  binary
+/.pnp.*              binary linguist-generated

.github/workflows/linting.yml

@@ -18,21 +18,21 @@ jobs:
       - name: Use Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: '16.x'
+          node-version: '18.x'
           cache: 'npm'
       - name: Install
-        run: npm install
+        run: yarn install
       - name: Run ESLint
-        run: npm run lint:js
+        run: yarn lint:js
       - name: Run Stylelint
-        run: npm run lint:css
+        run: yarn lint:css
       - name: Run Prettier
-        run: npm run prettier-check
+        run: yarn prettier-check
       - name: Build CSS
-        run: npm run build:css
+        run: yarn build:css
       - name: Build SCSS
-        run: npm run build:scss
+        run: yarn build:scss
       - name: Build Tokens
-        run: npm run build:tokens
+        run: yarn build:tokens
       - name: Build Storybook
-        run: npm run build-storybook
+        run: yarn build-storybook

.github/workflows/publish-storybook.yml

@@ -16,14 +16,14 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v3
         with:
-          node-version: '16.x'
+          node-version: '18.x'
           registry-url: 'https://registry.npmjs.org'
       - name: Install 🔧
         run: | # Install npm packages
-          npm ci
+          yarn install --immutable
       - name: Build 🔧
         run: | # build the Storybook files
-          npm run build-storybook
+          yarn build-storybook
       - name: Deploy 🚀
         uses: JamesIves/[email protected]
         with:

.github/workflows/release-package.yml

@@ -11,10 +11,10 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-node@v3
         with:
-          node-version: '16.x'
+          node-version: '18.x'
           registry-url: 'https://registry.npmjs.org'
-      - run: npm ci
-      - run: npm run build
+      - run: yarn install --immutable
+      - run: yarn build
       - run: npm publish --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
@@ -24,10 +24,10 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-node@v3
         with:
-          node-version: '16.x'
+          node-version: '18.x'
           registry-url: https://npm.pkg.github.com/
-      - run: npm ci
-      - run: npm run build
+      - run: yarn install --immutable
+      - run: yarn build
       - run: npm publish --access public
         env:
           NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}

.gitignore

@@ -4,6 +4,16 @@ node_modules/
 # Optional npm cache directory
 .npm
 
+# Yarn
+.pnp.*
+.yarn/*
+!.yarn/cache
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
 # Optional eslint cache
 .eslintcache
 
@@ -19,3 +29,6 @@ node_modules/
 
 # Distribution files
 dist
+public/design-tokens.source.json
+
+*storybook.log

.prettierignore

@@ -1,2 +1,3 @@
 # Tools
 tools/templates
+.yarn/*

.storybook/main.js

@@ -1,42 +1,42 @@
-/** @type { import('@storybook/html-webpack5').StorybookConfig } */
+import { join, dirname } from 'path'
+
+/**
+ * This function is used to resolve the absolute path of a package.
+ * It is needed in projects that use Yarn PnP or are set up within a monorepo.
+ */
+function getAbsolutePath(value) {
+  return dirname(require.resolve(join(value, 'package.json')))
+}
+
+/** @type { import('@storybook/html-vite').StorybookConfig } */
 const config = {
-  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
+  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
   addons: [
-    '@storybook/addon-links',
-    {
-      name: '@storybook/addon-essentials',
-      options: {
-        actions: false,
-      },
-    },
     {
       name: 'storybook-design-token',
       options: {
         preserveCSSVars: true,
       },
     },
     {
-      name: '@storybook/addon-styling',
+      name: '@storybook/addon-essentials',
       options: {
-        sass: {
-          // Require your Sass preprocessor here
-          implementation: require('sass'),
-        },
+        backgrounds: false,
       },
     },
-    '@storybook/addon-mdx-gfm',
+  ],
+  staticDirs: [
+    {
+      from: './assets',
+      to: '/public',
+    },
   ],
   framework: {
-    name: '@storybook/html-webpack5',
+    name: getAbsolutePath('@storybook/html-vite'),
     options: {},
   },
-  docs: {
-    autodocs: 'tag',
-  },
   core: {
     disableTelemetry: true, // 👈 Disables telemetry
   },
-  staticDirs: ['./public'],
 }
-
 export default config

.storybook/manager-head.html

@@ -0,0 +1,13 @@
+<style lang="sass">
+  button[data-action='collapse-root'] {
+    color: hsl(273, 22%, 18%);
+    text-transform: capitalize;
+    font-size: 12px;
+    letter-spacing: normal;
+    font-weight: 600;
+  }
+
+  #storybook-explorer-searchfield {
+    background-color: white;
+  }
+</style>

.storybook/manager.js

@@ -1,16 +1,6 @@
 import { addons } from '@storybook/manager-api'
-import rolemodelTheme from './rolemodelTheme'
+import OpticsTheme from './theme'
 
 addons.setConfig({
-  enableShortcuts: false,
-  theme: rolemodelTheme,
-  toolbar: {
-    fullscreen: { hidden: true },
-    outline: { hidden: true },
-    zoom: { hidden: true },
-    measure: { hidden: true },
-    backgrounds: { hidden: true },
-    viewport: { hidden: true },
-    grid: { hidden: true },
-  },
+  theme: OpticsTheme,
 })

.storybook/preview.js

@@ -1,36 +1,26 @@
-/** @type { import('@storybook/html').Preview } */
 import { useTheme } from './useTheme'
 
 const preview = {
-  decorators: [useTheme],
   parameters: {
     layout: 'centered',
     controls: {
       matchers: {
         color: /(background|color)$/i,
-        date: /Date$/,
+        date: /Date$/i,
       },
     },
     docs: {
       toc: {
         headingSelector: 'h2, h3',
-        title: 'Table of Contents',
+        title: 'On this page',
       },
     },
     options: {
       storySort: {
         order: [
+          'Introduction',
           'Overview',
-          [
-            'Introduction',
-            'Base Reset',
-            'Organization',
-            'Selective Imports',
-            'Tokens',
-            'Themes',
-            'Scale Overriding',
-            'Addons',
-          ],
+          ['Base Reset', 'File Organization', 'Selective Imports', 'Tokens', 'Themes', 'Scale Overriding', 'Addons'],
           'Tokens',
           'Utilities',
           'Navigation Components',
@@ -45,21 +35,22 @@ const preview = {
   },
 }
 
+import './preview.scss'
+
 export default preview
 
 export const globalTypes = {
-  themeMode: {
-    description: 'Color Theme Mode',
+  theme: {
+    name: 'Toggle theme mode',
+    description: 'Global theme mode for components',
     defaultValue: 'light',
     toolbar: {
-      title: 'Theme Mode',
-      icon: 'mirror',
-      items: [
-        { value: 'light', title: 'Light' },
-        { value: 'dark', title: 'Dark' },
-      ],
+      icon: 'circlehollow',
+      items: ['light', 'dark'],
+      showName: true,
+      dynamicTitle: true,
     },
   },
 }
 
-import './documentation.scss'
+export const decorators = [useTheme]

.storybook/documentation.scss → .storybook/preview.scss

@@ -6,12 +6,47 @@
 
 @import 'https://fonts.googleapis.com/css2?family=Tilt+Neon&display=swap';
 
-// Fix Table of contents scrolling
-html {
-  overflow: unset; // Optics sets this to handle flash messages
+.sbdocs.sbdocs-wrapper {
+  --toc-size: 20rem;
 
-  &:focus-within {
-    scroll-behavior: initial; // Modern CSS reset sets this to smooth
+  display: grid;
+  justify-items: center;
+  grid-template-columns: 1fr var(--toc-size);
+
+  .sbdocs.sbdocs-content + div {
+    width: 100%;
+    color: var(--op-color-neutral-base);
+
+    > div {
+      width: var(--toc-size);
+    }
+
+    .toc-wrapper {
+      .toc-list {
+        border-left: none;
+
+        .toc-list-item {
+          margin-left: var(--op-space-small);
+
+          > a {
+            color: var(--op-color-primary-plus-one);
+            text-decoration: underline;
+          }
+
+          &.is-active-li > a {
+            color: var(--op-color-primary-minus-one);
+            font-weight: var(--op-font-weight-bold);
+          }
+
+          &::before {
+            content: '-';
+            transform: translateX(calc(-1 * var(--op-space-small)));
+            border-left: none;
+            opacity: 1;
+          }
+        }
+      }
+    }
   }
 }
 
@@ -29,6 +64,7 @@ html {
   z-index: 1;
 }
 
+// Transition Demos
 .transition-demo {
   display: inline-block;
   padding: var(--op-space-medium);

.storybook/theme.js

@@ -0,0 +1,27 @@
+import { create } from '@storybook/theming'
+
+const theme = create({
+  base: 'light',
+  brandTitle: 'Optics, a RoleModel Design System',
+  brandUrl: 'https://docs.optics.rolemodel.design/',
+  brandImage: './public/optics-logo.svg',
+  brandTarget: '_self',
+  // UI
+  colorSecondary: 'hsl(216 48% 40%)', // --op-color-primary-base
+  appBg: 'hsl(216 48% 90%)', // --op-color-primary-plus-five
+  appContentBg: 'hsl(216 48% 90%)', // --op-color-primary-plus-five
+  appBorderColor: 'hsl(216 4% 90%)', // --op-color-border a.k.a --op-color-neutral-plus-five
+
+  // Typography
+  fontBase: "'Noto Sans', 'Noto Serif', sans-serif",
+  fontCode: 'monospace',
+
+  // Text colors
+  textColor: 'hsl(216 48% 20%)', // --op-color-primary-on-plus-five
+
+  // Toolbar default and active colors
+  barBg: 'hsl(216 4% 98%)', // --op-color-neutral-plus-eight
+  barTextColor: 'hsl(216 4% 4%)', // --op-color-neutral-on-plus-eight
+})
+
+export default theme