CLG-UI

CLG-UI is the shared React component library and design system maintained by the CLG team. It provides accessible, mobile-first foundations for React, Next.js, and Electron renderer applications.

Storybook is the component catalog, documentation website, and development workshop for the library.

Status: the design system foundations and first five component batches are complete. The project now builds as an installable Vite library and is being prepared for private GitHub Packages releases.

Design foundation

• Primary color: CLG Violet (#6258E9)
• Typeface: Nunito (400, 500, 600, and 700)
• Themes: light and dark
• Approach: semantic tokens, mobile first, accessible by default

Brand values live in the token layer. Components consume semantic CSS custom properties instead of hardcoded colors or typography decisions.

Component catalog

CLG-UI currently contains 17 components.

| Category | Components | | --- | --- | | Actions | Button, IconButton, Link | | Forms | Input, Textarea, Select, Checkbox, Radio, RadioGroup, Switch | | Data Display | Badge, Card | | Feedback | Alert, Spinner | | Overlays | Modal | | Typography | Heading, Text |

The catalog includes component variants, states, behavior examples, and foundation documentation for colors, typography, and spacing.

Compatibility

| Platform | Support | | --- | --- | | React | Supported | | Next.js | Supported when React client boundaries are respected | | Electron | Supported in React renderer processes | | React Native | Not supported | | Vue, Angular, or plain HTML | Require a separate adapter or implementation |

Visual components must not depend directly on Next.js, Electron, product state, or platform-specific APIs.

Getting started

Requirements

• Node.js 24 LTS (24.17.0 recommended in .nvmrc)
• Yarn 1.22.22

Yarn is the only project package manager. The required versions are recorded in .nvmrc and package.json. Do not generate or commit package-lock.json.

Installation

yarn install

Run Storybook

yarn storybook

Open http://localhost:6006.

Run the local application shell

yarn dev

The local shell is a visual composition preview only. It does not provide authentication, account creation, or data submission. Storybook runs as a separate development command and the preview does not assume that its local server is already available.

Quality checks

Run the complete validation pipeline before opening a pull request:

yarn validate

GitHub Actions runs the same validation on pull requests and pushes to master, using Node.js from .nvmrc and the committed Yarn lockfile.

The command runs:

yarn lint
yarn typecheck
yarn test:ci
yarn build:app
yarn build:lib
yarn validate:package
yarn build-storybook

Current baseline:

• 15 test suites;
• 32 behavior tests;
• application build;
• Storybook production build;
• desktop and 390 px mobile browser review;
• light and dark theme review.

Versioning and releases

CLG-UI follows semantic versioning through Changesets.

yarn changeset

Use patch for compatible fixes, minor for backward-compatible public features, and major for breaking public API or token changes.

When a release is ready, maintainers run yarn version-packages and open a version pull request containing the package version and changelog updates. After that pull request is merged, publishing a matching GitHub Release such as v0.1.0 validates and publishes the package to the private GitHub Packages registry.

Package publication is intentionally gated by the GitHub Release action. A normal merge to master never publishes a package.

The initial release is planned as 0.1.0.

Architecture

src/
  components/
    _internal/
      Field/              shared non-public field infrastructure
    Alert/
    Badge/
    Button/
    ...
    index.ts              public component barrel
  styles/
    tokens/
      _breakpoints.scss
      _layout.scss
      _primitives.scss
      _theme.scss
    global.scss
  storybook/
    foundations/
    Introduction.mdx
  utils/
  lib.ts                  public library entry point
docs/
  component-guidelines.md
  roadmap.md

Each public component is colocated with its implementation, Sass styles, Storybook stories, tests, and directory exports.

Internal modules under src/components/_internal are not part of the consumer API.

Intended package usage

The library build emits ESM JavaScript, TypeScript declarations, and a distributable stylesheet. After a version is published, applications consume it through:

import {
  Button,
  Card,
  Modal,
} from "@consulting-leadership-growth/clg-ui";
import "@consulting-leadership-growth/clg-ui/styles.css";

export function Example() {
  return (
    <Card>
      <Button>Continue</Button>
    </Card>
  );
}

Consumers must not import source files directly:

// Correct
import { Button } from "@consulting-leadership-growth/clg-ui";

// Incorrect
import { Button } from
  "@consulting-leadership-growth/clg-ui/src/components/Button/Button";

Creating a component

Read the Component Development Workflow and Component Guidelines before implementing or reviewing a component.

Every public component must provide:

• a small and explicit TypeScript API;
• semantic HTML and keyboard behavior;
• accessible names and visible focus;
• mobile-first styles using semantic tokens;
• light and dark theme support;
• Storybook documentation;
• behavior tests where relevant;
• public exports without internal implementation leakage.

Recommended structure:

ComponentName/
  ComponentName.tsx
  ComponentName.scss
  ComponentName.stories.tsx
  ComponentName.test.tsx
  index.ts

Contribution workflow

Start with CONTRIBUTING.md. It links the complete local setup, component, pull request, release, and package-consumption workflows.

Commit interactively with:

yarn commit

Common prefixes:

• feat: new behavior or component;
• fix: bug fix;
• docs: documentation only;
• test: test-only changes;
• refactor: internal change without public behavior changes;
• chore: tooling or repository maintenance.

Roadmap

The current phase prepares the Vite library for automated private releases:

1. automated CI and accessibility checks;
2. semantic versioning and Changesets;
3. React, Next.js, and Electron consumer validation;
4. private @consulting-leadership-growth/clg-ui publication.

Responsibilities, decisions, and acceptance criteria are tracked in the Project Roadmap.

Project documentation

• Contribution Guide
• Development Setup
• Component Development Workflow
• Component Guidelines
• Pull Request Workflow
• Releases and Private Publication
• Consuming CLG-UI
• Project Roadmap
• Persistent Project Memory

License and distribution

The repository is currently private and marked UNLICENSED. This means it is internal proprietary software and does not grant public reuse rights.

The package will be published privately through GitHub Packages as @consulting-leadership-growth/clg-ui. Access will follow the CLG GitHub organization and repository permissions.