General Provisions
Purpose and Scope
This document defines mandatory requirements for organizing and maintaining internal corporate npm libraries within the company’s front-end ecosystem. Its goal is to ensure consistent code quality, reliability, and developer experience across all packages. The rules apply to every library, regardless of its functional domain (e.g., filtering, notifications, input components), and cover all stages – from initial development to publication and usage in host applications.
Guiding Principles
Consistency
All libraries must adhere to a unified structure, coding style, and documentation format. Shared configurations for linting (ESLint), formatting (Prettier), and style validation (Stylelint) enforce this uniformity, making the codebase predictable and reducing onboarding effort.
Reusability
Libraries expose well-defined public APIs that are documented and versioned. Components, services, and utilities are built to be consumed independently of a specific project, enabling their safe reuse across multiple applications.
Strict Typing
TypeScript’s strict mode is mandatory. The use of any is prohibited except in exceptional, explicitly justified cases. Every public contract (inputs, outputs, service methods, configuration interfaces) must be fully typed, providing robust compile‑time guarantees.
Testability and Documentation
Every library must include automated tests that verify behaviour and styling. Additionally, all components must be showcased in Storybook with interactive examples and configurable controls. A Storybook story is part of the Definition of Done for any new or modified component.
Definitions
Library / Package
An independently versioned, publishable npm package (e.g., @company/filter, @company/notification). It contains a cohesive set of Angular components, services, directives, and related assets.
Component
An Angular component exported by a library. It must support customizable styles through SCSS variables and be accompanied by corresponding stories and tests.
Theme
A collection of global CSS custom properties (e.g., --grain-font-family, --grain-primary-color) that control the default appearance of all libraries. Libraries also define component‑scoped variables for fine‑grained customization, following the two‑level cascade pattern.
Global Variable
A CSS custom property prefixed with --grain- that is shared across all libraries. Changing a global variable affects all components that reference it.
Component Variable
A CSS custom property unique to a specific component (e.g., --slider-font-family). It allows overriding a single component’s style without affecting others. The recommended pattern is var(--grain-font-family, var(--slider-font-family, default)).
Storybook
An interactive development environment used to document, test, and showcase components in isolation. A complete set of stories is a required deliverable for every component.
Definition of Done (DoD)
For a library component, DoD includes:
Full TypeScript typing with strict mode enabled.
Unit and style tests meeting coverage thresholds.
All linting and formatting checks passing.
At least one Storybook story that demonstrates the component’s features and allows styling adjustments via controls.
Updated README describing the component’s API and its configurable SCSS variables.
Technology Stack
Angular: The primary framework. Libraries are built as Angular libraries using Angular Package Format.
TypeScript: Strict configuration is required.
SCSS: Stylesheets use SCSS syntax. All values are exposed through CSS custom properties, and a two‑level variable cascade provides theming flexibility.
ESLint & Prettier: Code quality and formatting are enforced with company‑wide shared configurations.
Karma / Angular Testing Library: Standard tools for unit and component testing.
Storybook: Required for interactive component documentation and visual testing.
Stylelint: Validates SCSS files and ensures adherence to the defined variable conventions.
All tools must be integrated into the CI pipeline, and their checks must pass before any merge or publication.