Skill Maps

Documentation as a team product

You can leave Storybook “out of the box,” but for a DS it helps to brand it as the team’s product: logo, manager colors, section order — and publish static files to a URL everyone uses.

Theming the Manager UI

Via @storybook/theming and .storybook/manager.js:

import { addons } from '@storybook/manager-api';
import { create } from '@storybook/theming/create';

addons.setConfig({
  theme: create({
    base: 'light',
    brandTitle: 'Skill Maps DS',
    brandUrl: '/',
    brandImage: './ds-logo.svg',
    colorPrimary: '#0B6E4F',
    colorSecondary: '#0B6E4F',
    appBg: '#F7F7F5',
    appBorderRadius: 8,
  }),
});

Do not confuse manager theme (Storybook chrome) with preview theme (how the component itself looks). Preview is themed with product tokens in preview.js.

Navigation and IA

  • Group: Foundations (color, type, spacing), Components, Patterns.
  • In parameters.options.storySort set order so Button is not lost under “Example/…”.
options: {
  storySort: {
    order: ['Foundations', 'Components', ['Button', 'Input', 'Card'], 'Patterns'],
  },
},

Building static output

npm run build-storybook

By default the artifact is in storybook-static/. It is a normal static site (HTML/JS/CSS).

Deploy: basic options

  1. Netlify / Vercel / GitHub Pages — publish the storybook-static folder.
  2. Chromatic — hosting + visual regression from the same build.
  3. Internal nginx — if the DS is private.

Example idea for Netlify: a separate site or branch deploy, publish = storybook-static, build command npm run build-storybook. Restrict access if the library is internal (Netlify password, SSO, VPN).

CI

Minimum:

  • on PR — build-storybook (catch broken imports);
  • optionally — publish a preview URL;
  • later — Chromatic / Playwright screenshots (testing module).

Versioning the docs

For a published npm package it helps to:

  • show the package version in brandTitle (Skill Maps DS v1.4.0);
  • keep previous major docs (v1 / v2) if the API diverged a lot.

Checklist: “safe to share the link”

  • Tokens and fonts are wired; UI does not “jump.”
  • Foundations + key Components are present.
  • A11y addon is enabled.
  • Custom brand does not hurt sidebar readability.
  • build-storybook is green in CI.
  • The URL is known to the team (package README + company portal).

Practice

  1. Configure manager theme with the DS name.
  2. Sort the stories tree.
  3. Build storybook-static and deploy to a preview environment.
  4. Put the link in the design system README.

Docs without a URL are a diary in a drawer. Docs with a URL and a current build are a working product tool.