From e6127698bb5f06d5f8b33b66d63564f4b04c8d1c Mon Sep 17 00:00:00 2001 From: Maria Garcia Luque Date: Sat, 18 Jul 2026 12:23:22 +0200 Subject: [PATCH] [design-system] Release 0.3.0: version bump + CHANGELOG for the component-system batch --- packages/design-system/CHANGELOG.md | 27 +++++++++ packages/design-system/README.md | 92 +++++++++++++++++++++++++++-- packages/design-system/package.json | 2 +- 3 files changed, 116 insertions(+), 5 deletions(-) create mode 100644 packages/design-system/CHANGELOG.md diff --git a/packages/design-system/CHANGELOG.md b/packages/design-system/CHANGELOG.md new file mode 100644 index 0000000..76a4fb8 --- /dev/null +++ b/packages/design-system/CHANGELOG.md @@ -0,0 +1,27 @@ +# Changelog + +All notable changes to `@fireflyframework/design-system` will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [0.3.0] - 2026-07-18 + +### Added +- `ff-icon` primitive with the injectable, mergeable `FF_ICONS` registry and `provideFfIcons()` — pack-agnostic SVG icons (sm/md/lg, aria-hidden by default, `role="img"` with `label`) +- `ff-panel` primitive: `card`/`alert` appearances, semantic variants, `heading` input plus `[ff-panel-heading]`/`[ff-panel-actions]`/`[ff-panel-footer]` projection slots +- `ff-progress` primitive: accessible determinate progress bar (`role="progressbar"`, clamped value, `showValue`) +- `ff-skeleton` primitive: text/rect/circle placeholders, multi-line text, shimmer honouring `prefers-reduced-motion` +- `ff-empty-state` primitive with projected `[ff-empty-state-icon]` and actions slot +- `ff-tab-bar` — first composition-tier **pattern** (composes `ff-icon` + `ff-badge` only): underline/pills tab strip with tablist semantics and roving-tabindex keyboard navigation +- `ControlValueAccessor` support in `ff-input`, `ff-checkbox`, `ff-radio` and `ff-select` — Reactive Forms and ngModel now work; the classic `value`/`valueChange` API keeps working when no forms directive is attached +- Design tokens are now shipped with the package (`tokens/` copied into the dist with a `./tokens` exports entry) so consumers can `@use` the token sheets + +### Changed +- New peer dependency: `@angular/forms ^21.2.0` (required by the CVA-enabled form primitives) + +## [0.2.0] and earlier + +Released before this changelog existed (18 original `ff-*` primitives, design tokens with dark mode). See git history. diff --git a/packages/design-system/README.md b/packages/design-system/README.md index 3369998..d6ee083 100644 --- a/packages/design-system/README.md +++ b/packages/design-system/README.md @@ -1,7 +1,91 @@ -# design-system +# @fireflyframework/design-system -This library was generated with [Nx](https://nx.dev). +Reference implementation of the **Firefly Design System**: standalone Angular components (`ff-*`), design tokens (`--ff-*`) and theming hooks used by Firefly products. Programs against — and is verified by — [`@fireflyframework/design-system-contract`](../design-system-contract/README.md). -## Running unit tests +## Install -Run `nx test design-system` to execute the unit tests. +Published to GitHub Packages: + +```bash +npm install @fireflyframework/design-system +# peer deps: @angular/common ^21.2, @angular/core ^21.2, @angular/forms ^21.2 +``` + +## What's inside + +**23 primitives** — `ff-button`, `ff-icon-button`, `ff-badge`, `ff-loader`, `ff-input`, `ff-checkbox`, `ff-radio`, `ff-select`, `ff-card`, `ff-dialog`, `ff-toast`, `ff-banner`, `ff-bottom-sheet`, `ff-divider`, `ff-chip`, `ff-link`, `ff-avatar`, `ff-tooltip`, `ff-icon`, `ff-panel`, `ff-progress`, `ff-skeleton`, `ff-empty-state`. + +**1 pattern** — `ff-tab-bar` (composes `ff-icon` + `ff-badge`). + +Composition hierarchy is strict and contract-verified: *primitives compose nothing; patterns compose only primitives; layouts (upcoming) never compose layouts.* + +All components are `standalone: true`, `OnPush`, signal-based (`input()`/`output()`), BEM-classed and themable exclusively through CSS custom properties. + +## Usage + +```ts +import { FfButtonComponent, FfPanelComponent } from '@fireflyframework/design-system'; + +@Component({ + standalone: true, + imports: [FfButtonComponent, FfPanelComponent], + template: ` + + Something needs your attention. + Dismiss + + `, +}) +export class ExampleComponent {} +``` + +### Forms (ControlValueAccessor) + +`ff-input`, `ff-checkbox`, `ff-radio` and `ff-select` implement `ControlValueAccessor` — they work with Reactive Forms and `ngModel`. The classic `value`/`valueChange` API keeps working when no forms directive is attached. + +```html + +``` + +### Icons + +`ff-icon` renders named SVG paths from an injectable, mergeable registry — bring your product's icon set: + +```ts +// app.config.ts +import { provideFfIcons } from '@fireflyframework/design-system'; + +providers: [provideFfIcons({ check: 'M9 16.2 4.8 12l-1.4 1.4L9 19 21 7l-1.4-1.4z' })]; +``` + +```html + + +``` + +## Design tokens & theming + +Token sheets ship with the package (`./tokens` export): + +```scss +// styles.scss +@use '@fireflyframework/design-system/tokens' as *; +``` + +- Tokens are CSS custom properties on `:root` (`--ff-color-*`, `--ff-spacing-*`, `--ff-radius-*`, `--ff-font-*`, `--ff-elevation-*`), with per-component tokens (`--ff-button-*`, `--ff-panel-*`, …) for scoped customization. +- **Dark mode**: `[data-theme="dark"]` on `` (falls back to `prefers-color-scheme`). +- **Runtime theming per tenant**: `TenantThemeService` in `@fireflyframework/core` overrides the same tokens at runtime — cascade: defaults → tenant → dark → tenant-dark. + +## Living catalog + +The monorepo's `playground` app is the catalog: every component with its real variants, a foundations page rendering the token scales, and a theming page with dark toggle + token inspector. + +```bash +pnpm nx serve playground +``` + +## Further reading + +- Decoupling contract: `@fireflyframework/design-system-contract` (component contracts, required tokens, hierarchy verifier). +- Architecture, Hub UI equivalence matrices and migration strategy: [`docs/firefly-design-system-catalog-and-flydocs-migration.md`](../../docs/firefly-design-system-catalog-and-flydocs-migration.md). +- Changelog: [CHANGELOG.md](./CHANGELOG.md). diff --git a/packages/design-system/package.json b/packages/design-system/package.json index 22d5979..c19ce39 100644 --- a/packages/design-system/package.json +++ b/packages/design-system/package.json @@ -1,6 +1,6 @@ { "name": "@fireflyframework/design-system", - "version": "0.2.0", + "version": "0.3.0", "publishConfig": { "registry": "https://npm.pkg.github.com" },