@ids-group-ltd/ids-design-system 0.1.0

package/README.md

@@ -0,0 +1,114 @@
+# IDS Design System
+
+Angular component library, design tokens and themes for IDS Group products.
+
+- 45+ standalone components (buttons, forms, overlays, navigation, data display)
+- Three-tier token architecture: palette → semantic theme → geometry/typography/motion tokens
+- Bundled fonts (Mulish, JetBrains Mono) — no external font CDN required
+- Built for Angular 21, zoneless-compatible, `sideEffects: false`
+
+## Installation
+
+```bash
+npm install @ids-group-ltd/ids-design-system
+```
+
+Requires Angular `^21.2.0` (`@angular/core`, `common`, `forms`, `router`, `platform-browser`) and `@angular/cdk` as peer dependencies.
+
+## Setup
+
+### 1. Global styles
+
+Add the package to your Sass include paths in `angular.json`:
+
+```json
+"architect": {
+  "build": {
+    "options": {
+      "stylePreprocessorOptions": {
+        "includePaths": ["node_modules/@ids-group-ltd/ids-design-system"]
+      }
+    }
+  }
+}
+```
+
+Then import the design system once at the top of your root `styles.scss`:
+
+```scss
+@use 'styles/ds';
+```
+
+This brings in the default palette, semantic theme, design tokens, fonts, reset and base typography.
+
+Advanced consumers can swap the palette/theme and keep the token layer — global side-effects (fonts, link styles, etc.) become opt-in:
+
+```scss
+@use 'themes/default/palette';
+@use 'themes/default/theme';
+@use 'styles/tokens';
+@use 'styles/fonts';
+```
+
+### 2. Components
+
+All components are standalone — import them directly:
+
+```ts
+import { Component } from '@angular/core';
+import { ButtonComponent } from '@ids-group-ltd/ids-design-system';
+
+@Component({
+  selector: 'app-example',
+  imports: [ButtonComponent],
+  template: `<ds-button variant="outline" icon="download">Export</ds-button>`,
+})
+export class ExampleComponent {}
+```
+
+## Development
+
+This repo contains the library (`src/`) and a documentation app (`ds-docs/`).
+
+```bash
+npm run build        # build the library into dist/ds
+npm start            # serve the docs app
+npm run build:docs   # build the docs app
+```
+
+## Releasing
+
+Releases follow [SemVer](https://semver.org): `fix` → patch, new backwards-compatible
+features → minor, breaking changes (API or visual) → major. A new Angular major
+always means a new package major. See `CHANGELOG.md` for history.
+
+Publishing runs in CI (Bitbucket Pipelines): pushing a `vX.Y.Z` tag builds the
+library and publishes it to npm. To cut a release, with a clean working tree:
+
+```bash
+npm run release:patch   # 0.1.0 -> 0.1.1  bugfixes
+npm run release:minor   # 0.1.0 -> 0.2.0  new components/inputs/tokens
+npm run release:major   # 0.x   -> 1.0.0  breaking changes
+
+git push origin main --follow-tags   # the tag push triggers CI publish
+```
+
+Each `release:*` bumps the version and creates a `release: x.y.z` commit plus a
+`vX.Y.Z` git tag locally — it does **not** publish. The tag push to Bitbucket
+runs `bitbucket-pipelines.yml`, which builds and publishes `dist/ds`. Add a
+`CHANGELOG.md` entry before releasing.
+
+CI auth uses a Secured repository variable `NPM_TOKEN` (npm granular access
+token, read+write on `@ids-group-ltd`, "Bypass 2FA" enabled).
+
+Manual publish (fallback, requires an authenticated npm session):
+
+```bash
+npm run publish:manual
+```
+
+Pre-releases: `npm version prerelease --preid=beta`, then `npm publish ./dist/ds --tag next`.
+
+## License
+
+UNLICENSED — proprietary to IDS Group Ltd.