Atlas Copco VT Lite Site Generator

Standalone Lite Site Generator package for Atlas Copco VT. This package contains the LSG component set, Storybook documentation, and themed AEM-ready CSS/JS outputs.

Tech stack

• React 18 + TypeScript
• Storybook 7 with @storybook/nextjs
• SCSS + Tailwind CSS + PostCSS
• Next.js 13 to preserve the existing Storybook/runtime foundation

Getting started

# Install dependencies
npm install

# Run Storybook (default: http://localhost:6006)
npm run storybook

# Build static Storybook
npm run build-storybook

Scripts

| Script | Description | |---------------------|--------------------------------| | npm run storybook | Start Storybook dev server | | npm run build-storybook | Build static Storybook | | npm run build:npm | Build the component library plus all themed assets | | npm run build:themes:css | Emit theme-1.css, theme-2.css, theme-3.css | | npm run build:themes:js | Emit theme-1.js, theme-2.js, theme-3.js | | npm run dev | Start Next.js dev server | | npm run build | Build Next.js app | | npm run lint | Run ESLint |

Project structure

.storybook/           # Storybook config, theme, preview
src/
  components/lsg/     # Shared base LSG React components, docs, and clientlib runtime
  themes/             # Theme component wrappers plus Theme 1 / 2 / 3 CSS and JS entry points
  stories/foundation/_components/  # Minimal Storybook layout helpers used by LSG docs
  utils/styles/       # Shared spacing/style primitives still used by LSG SCSS
public/               # Static assets

Architecture layers

1. Base layer: src/components/lsg/ contains the shared structural components and the common SCSS each theme builds from.
2. Theme layer: each folder under src/themes/ exposes its own themed component set that wraps the base components and can add extra theme-specific styling on top.
3. Brand layer: the --lsg-* CSS custom properties define the brand contract for colours, fonts, radii, and sizes. Each brand/theme supplies its own values for that contract.

How themes work

Themes are built as an extension model, not as separate rewrites of the component library.

1. Base components

The shared implementation lives under src/components/lsg/.

• This layer contains the React structure and the common SCSS for LsgButton, LsgHeader, LsgFooter, and the rest of the LSG set.
• Base components should own the shared markup, accessibility, interaction logic, and stable AEM-facing class names.
• Base SCSS should use the --lsg-* token contract instead of hardcoding a brand style.

This is the layer every theme builds on top of.

2. Theme components

Each theme has its own component entrypoint under src/themes/<theme>/components.tsx.

• Theme components are wrappers around the base components.
• The wrapper generation happens in src/themes/createThemeComponents.tsx.
• Each wrapper adds theme-specific classes such as lsg-themed-component--theme-1 so a theme can target the base component with extra styling.

That means the theme can keep the shared functionality from the base component while still changing the presentation or adding a branded treatment.

Example flow:

1. Theme1LsgButton renders the shared LsgButton.
2. The wrapper adds the lsg-themed-component--theme-1 class.
3. src/themes/theme-1/components.scss applies extra styles to the shared .lsg-button markup inside that theme wrapper.

3. Brand variables

The brand layer is the CSS variable contract.

• Tokens such as --lsg-color-primary, --lsg-font-family-primary, and --lsg-radius-rounded define the brand values.
• The default contract lives in src/components/lsg/lsg-tokens.scss.
• Each theme entry file overrides those same variables in its own :root block.

This keeps the API stable. Components always read the same variables, while each brand provides different values for them.

Storybook theme behavior

Storybook switches themes at runtime.

• The toolbar is configured in .storybook/preview.tsx through globalTypes.lsgTheme.
• The LSG_THEMES object maps a theme name to a set of --lsg-* values.
• The withLsgTheme decorator turns the selected theme into a :root CSS block and injects it into the preview document.
• The decorator also sets document.documentElement.dataset.lsgTheme = themeKey.

That data-lsg-theme attribute is important because the theme SCSS can target either:

• the whole Storybook canvas through :root[data-lsg-theme="theme-x"]
• a specific themed wrapper through .lsg-themed-component--theme-x

So in Storybook you get both:

• brand token swapping for colours, typography, spacing, and radii
• theme-specific component styling layered on top of the shared components

Production theme outputs

Each theme has its own CSS and JS bundle.

• src/themes/theme-1/theme.scss, src/themes/theme-2/theme.scss, and src/themes/theme-3/theme.scss import the shared LSG styles and their own theme component styles.
• Those files also override the :root token contract for that theme.
• build:themes:css emits one CSS file per theme.
• build:themes:js emits one JS file per theme for clientlib runtime behavior.

This is the AEM delivery model:

1. Shared component structure comes from the base implementation.
2. Theme CSS adds component-level extensions.
3. Theme variables apply the brand colours, fonts, and sizes.
4. Theme JS boots the runtime behavior for that theme.

When to use each layer

• Use the base component layer when the change should apply to every theme.
• Use the theme component layer when a theme needs a distinct visual treatment on top of the shared component behavior.
• Use the token layer when the change is a brand value such as colour, typeface, size, or border radius.

As a rule, put structure and behavior in the base component first. Only move into src/themes/ when the theme genuinely needs its own component styling on top of that shared core.

Adding a new themed component

1. Add or update the shared component in src/components/lsg/.
2. Keep the base SCSS driven by var(--lsg-*) tokens.
3. Add theme-specific styling in src/themes/<theme>/components.scss if that theme needs more than token changes.
4. Export the theme wrapper from src/themes/<theme>/components.tsx.
5. If needed in Storybook, add or update the theme values in .storybook/preview.tsx.

Adding components

1. Add a component under src/components/lsg/<Name>/ and keep its styles as plain .scss so AEM-facing class names stay stable.
2. Add *.stories.tsx or MDX docs alongside that component in src/components/lsg/.
3. If a theme needs more than brand variables, add its component-level extensions under src/themes/<theme>/components.scss and expose a themed wrapper from src/themes/<theme>/components.tsx.
4. Use the root token contract from src/components/lsg/lsg-tokens.scss and prefer var(--lsg-*) values over hardcoded theme colours.

Design tokens

• Core colours: --lsg-color-primary, --lsg-color-secondary, --lsg-color-tertiary, --lsg-color-light, --lsg-color-dark, --lsg-color-black, --lsg-color-white
• Typography: --lsg-font-family-primary, --lsg-font-family-secondary, plus --lsg-size-* scale tokens
• Shape: --lsg-radius-square, --lsg-radius-rounded, --lsg-radius-pill

Theme-specific overrides live under src/themes/, but they extend the shared base components instead of replacing the root --lsg-* contract.