@gostudent/shared-ui-library

A React component library built with React 18, TypeScript, Vite, and CSS Modules. Provides reusable UI components with multi-brand theme support for GS and SK.

Tech Stack

• React 18 - Modern React with hooks and concurrent features
• TypeScript - Type-safe component development
• Vite - Fast build tool and dev server
• CSS Modules - Scoped styling
• Storybook - Component development and documentation
• Style Dictionary - Design token pipeline from Figma

Installation

npm install @gostudent/shared-ui-library

Usage

Importing Components

import { Button } from '@gostudent/shared-ui-library';
import '@gostudent/shared-ui-library/themes/theme-gs.css'; // or theme-sk.css
import '@gostudent/shared-ui-library/themes/style.css';

Using Components

function App() {
  return (
    <Button variant="primary" size="md" onClick={() => console.log('Clicked!')}>
      Click Me
    </Button>
  );
}

Brand Themes

The library supports two brand themes — GS and SK — applied via the data-theme attribute:

<div data-theme="gs">
  <Button variant="primary">GS Button</Button>
</div>

<div data-theme="sk">
  <Button variant="primary">SK Button</Button>
</div>

Theme CSS files:

• @gostudent/shared-ui-library/themes/theme-gs.css — GoStudent brand
• @gostudent/shared-ui-library/themes/theme-sk.css — Studienkreis brand

All component styles reference CSS custom properties generated from design tokens. No hardcoded colors.

Design Token Pipeline

Tokens are exported from Figma and processed via Style Dictionary.

Running the pipeline

npm run build:tokens

Output: src/tokens/output/{base,gs,sk}/

Each output directory contains:

• variables.css — CSS custom properties
• tokens.ts / tokens.js — JS/TS exports
• tokens.d.ts — TypeScript declarations

Token categories

| Category | Scope | Examples | |---|---|---| | Global Colours | base | --grey-700, --functional-white | | Spacing | base | --spacing-xxs, --spacing-xl | | Radius | base | --radius-sm, --radius-lg | | Font (desktop) | base | --font-desktop-size-sm, --font-desktop-line-height-md | | Font (mobile) | base | --font-mobile-size-sm | | Breakpoints | base | --breakpoint-desktop-full-screen, --breakpoint-tablet-layout-grid-width | | Brand colours | gs | --blue-500, --pink-50, --purple-500 | | Brand colours | sk | --blue-500, --red-500, --green-300 |

Token imports

// CSS variables
import '@gostudent/shared-ui-library/tokens/base/variables.css';
import '@gostudent/shared-ui-library/tokens/gs/variables.css';

// JS/TS token objects
import { t } from '@gostudent/shared-ui-library/tokens/base';
import { t } from '@gostudent/shared-ui-library/tokens/gs';

Syncing from Figma

1. In Figma: Plugins > Development > Export Design Tokens — downloads figma-tokens.zip
2. Extract into figma-tokens/ (preserve $themes.json and $metadata.json — never overwrite these)
3. Run npm run build:tokens

Development

Prerequisites

• Node.js 20+ and npm

Setup

npm install
npm run dev          # Vite dev server
npm run storybook    # Storybook on port 6006

Building

npm run build           # Build tokens + TypeScript + Vite
npm run build-storybook # Build Storybook static site

Local development against web-app

To develop the library locally and test changes in the web-app without publishing:

npm run dev:copy

This watches for changes, builds on each change, and copies the output directly into the web-app's node_modules:

../web-app/legacy/node_modules/@gostudent/shared-ui-library

Minification is automatically disabled when COPY_TO is set (faster rebuilds, readable output for debugging).

Web-app requirements:

The web-app's webpack config must handle CSS from @gostudent packages:

// webpack config
{
  test: /\.css$/,
  include: /node_modules\/@gostudent/,
  use: ['style-loader', 'css-loader'],
}

And the web-app entry must import both the theme and component styles:

import '@gostudent/shared-ui-library/themes/theme-gs.css'; // or theme-sk.css
import '@gostudent/shared-ui-library/themes/style.css';

Testing

npm test              # Watch mode
npm run test:ci       # Run once with coverage (JUnit + default reporters)
npm run test:coverage # Coverage report

Tests use Vitest + React Testing Library in a jsdom environment.

Linting & Type Checking

npm run lint          # ESLint (max-warnings: 0)
npm run lint:fix      # Auto-fix ESLint issues
npm run type-check    # TypeScript check without emitting

Project Structure

src/
├── components/          # Component library
│   └── Button/
│       ├── Button.tsx
│       ├── Button.module.css
│       ├── Button.stories.tsx
│       ├── Button.test.tsx
│       └── index.ts
├── themes/              # Brand theme files
│   ├── theme-gs.css
│   └── theme-sk.css
├── tokens/
│   └── output/          # Generated — do not edit manually
│       ├── base/        # Shared tokens (colours, spacing, radius, fonts, breakpoints)
│       ├── gs/          # GS brand colours
│       └── sk/          # SK brand colours
└── index.ts             # Library entry point

figma-tokens/            # Figma plugin token exports (source of truth)
scripts/
└── build-tokens.mjs     # Style Dictionary build script

Creating New Components

For the full step-by-step guide (token sync, Figma import, Storybook generation), see docs/contributing-components.md or the Confluence page.

1. Create a folder in src/components/ComponentName/
2. Add the component files:
   • ComponentName.tsx — implementation
   • ComponentName.module.css — styles using CSS Modules
   • ComponentName.stories.tsx — Storybook stories
   • ComponentName.test.tsx — Vitest tests
   • index.ts — barrel export
3. Reference token CSS variables in styles:

   .myComponent {
     background-color: var(--color-primary);
     color: var(--color-text-primary);
   }

4. Export from src/index.ts

Available Components

• Button — Versatile button component with multiple variants and sizes

CI/CD

GitLab CI stages:

1. check — lint, type-check, tests, version checks
2. prerelease — manual deploy for feature branches (DT-*, A20-*)
3. release — manual deploy from master

Published to npm as @gostudent/shared-ui-library via semantic-release.

License

MIT