@frame-kit/ui-ng 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FrameKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# @frame-kit/ui-ng
+
+A **style-agnostic, token-driven Angular UI component library.** Components own structure, layout,
+accessibility, and behavior; their entire appearance comes from `--fk-*` CSS custom properties, so you
+theme the whole library by supplying tokens — never by overriding component CSS.
+
+- **Standalone + OnPush + signal inputs** throughout (Angular 21+).
+- **Tree-shakeable** — every component is its own entry point, so you only ship what you import.
+- **Themeable** via [`@frame-kit/tokens`](https://www.npmjs.com/package/@frame-kit/tokens) and your own `--fk-*` overrides.
+
+## Install
+
+```bash
+npm i @frame-kit/ui-ng @frame-kit/tokens
+```
+
+Peer dependencies: `@angular/{core,common,forms,router,platform-browser,cdk}` ^21.2 and `rxjs` ^7.
+
+## Quick start
+
+**1. Load the default theme** (in `angular.json` → `styles`, order matters):
+
+```jsonc
+"styles": [
+  "node_modules/@frame-kit/tokens/base.css",
+  "node_modules/@frame-kit/tokens/dark.css", // optional dark mode
+  "src/styles.css" // your overrides last
+]
+```
+
+**2. Register the icons your app uses** (the library ships none):
+
+```ts
+import { provideIcons } from '@frame-kit/ui-ng';
+import { searchIcon, lockIcon } from 'your-icon-source';
+
+export const appConfig = {
+  providers: [provideIcons({ search: searchIcon, lock: lockIcon })],
+};
+```
+
+**3. Import components where you use them** (standalone):
+
+```ts
+import { Component } from '@angular/core';
+import { ButtonComponent } from '@frame-kit/ui-ng';
+
+@Component({
+  selector: 'app-example',
+  imports: [ButtonComponent],
+  template: `<fk-button variant="primary">Save</fk-button>`,
+})
+export class ExampleComponent {}
+```
+
+Both forms work and tree-shake identically — the barrel `@frame-kit/ui-ng` or the per-component entry
+point `@frame-kit/ui-ng/ui/button`. Use the barrel unless you have a reason not to.
+
+## Documentation
+
+- **[Component catalog](./COMPONENTS.md)** — every component, with a link to its full README.
+- **[Theming guide](./THEMING.md)** — the `--fk-*` token contract and how to override appearance.
+- **[Development guide](./DEVELOPMENT_GUIDE.md)** — for contributing components.
+
+Each component also ships its own `README.md` inside the package.
+
+## License
+
+MIT

package/THEMING.md

@@ -0,0 +1,130 @@
+# Theming `@frame-kit/ui-ng`
+
+`@frame-kit/ui-ng` is **style-agnostic**. Components define structure, layout,
+accessibility, and behavior; their appearance comes entirely from `--fk-*` CSS custom
+properties (design tokens). You theme the library by supplying or overriding those tokens —
+never by editing component CSS.
+
+---
+
+## Quick start
+
+```bash
+npm i @frame-kit/ui-ng @frame-kit/tokens
+```
+
+```ts
+// app config — register the icons your app uses (the library ships none)
+import { provideIcons } from '@frame-kit/ui-ng';
+import { searchIcon, lockIcon } from 'your-icon-source';
+
+export const appConfig = {
+  providers: [provideIcons({ search: searchIcon, lock: lockIcon })],
+};
+```
+
+```jsonc
+// angular.json → architect.build.options.styles (order matters)
+"styles": [
+  "node_modules/@frame-kit/tokens/base.css",   // default neutral theme
+  "node_modules/@frame-kit/tokens/dark.css",   // optional dark mode
+  "src/styles.css"                              // YOUR overrides come last
+]
+```
+
+That's it — components now render with the default neutral theme.
+
+---
+
+## How it works (three layers)
+
+```css
+/* 1. Component (ui-ng) — reads tokens with a triple fallback, never hardcodes */
+.fk-button--primary {
+  background: var(--fk-button-primary-bg, var(--fk-color-primary, #2563eb));
+}
+
+/* 2. @frame-kit/tokens base.css — defines the defaults in :root */
+:root {
+  --fk-color-primary: #2563eb;
+  --fk-button-primary-bg: var(--fk-color-primary);
+}
+
+/* 3. Your app — re-declares only what you want, AFTER the import → cascade wins */
+:root {
+  --fk-color-primary: #7c3aed;
+} /* your brand — buttons, links, focus all follow */
+```
+
+You never edit `node_modules`. You layer a thin override stylesheet on top.
+
+---
+
+## Overriding tokens
+
+**Two tiers — choose your blast radius:**
+
+- Override a **primitive** (`--fk-color-primary`, `--fk-radius-md`, `--fk-font-size-md`) → cascades everywhere.
+- Override a **component token** (`--fk-button-primary-bg`) → affects only that component.
+
+```css
+:root {
+  --fk-color-primary: #7c3aed; /* sweeping brand change */
+  --fk-radius-md: 4px;
+  --fk-font-family-base: 'Geist', sans-serif;
+  --fk-button-primary-bg: #111; /* surgical: buttons only */
+}
+```
+
+**Scope it** to part of the DOM (tokens inherit down the tree):
+
+```css
+.marketing {
+  --fk-color-primary: #e11d48;
+} /* only this subtree */
+```
+
+**Runtime theming** (no rebuild — they're live CSS variables):
+
+```ts
+document.documentElement.style.setProperty('--fk-color-primary', userColor);
+```
+
+**Dark mode** ships in `dark.css`: it activates on the system preference
+(`prefers-color-scheme: dark`) and on an explicit `html.dark` class (which wins). Toggle dark
+mode by adding/removing `dark` on `<html>`.
+
+---
+
+## The rules (contract)
+
+These govern what is and isn't themeable. Contributors must follow them; the guardrail spec
+(`tokens/src/contract.guardrail.spec.ts`) enforces R7.
+
+- **R1 — Appearance is tokenized; structure is not.** Color, background, border-color, radius,
+  font, spacing/rhythm, shadow, transition, opacity → `var(--fk-*)`. `display`, flex/grid,
+  positioning, functional `z-index`, internal geometry → raw CSS, not a customization point.
+- **R2 — Two tiers.** Primitives hold brand values; component tokens reference primitives via `var()`.
+- **R3 — Triple fallback.** `var(--fk-component-x, var(--fk-primitive, <hardcoded>))` — always renders.
+- **R4 — Components consume only `--fk-*` for themeable props** (no raw hex/rgba/hsl as direct values).
+- **R5 — Naming:** `--fk-<scope>-<prop>[-variant][-state]` (e.g. `--fk-button-primary-bg-hover`).
+- **R6 — Encapsulation:** default `Emulated`. No `::ng-deep` / `ViewEncapsulation.None` / `!important` for theming.
+- **R7 — `@frame-kit/tokens` defines a default for every primitive consumed.** Enforced by the guardrail.
+- **R8 — Dark mode remaps color tokens only**, never structural ones.
+
+### Sanctioned exceptions to R6
+
+A few uses of `::ng-deep` / `!important` are intentional and **not** for theming (no colors leak):
+
+- `core/icon` — `:host ::ng-deep svg` sizes the SVG injected via `[innerHTML]` (unscoped by design).
+- `ui/dialog` — `::ng-deep [fkDialogFooter]/[fkDialogActions]` styles **consumer-projected** content.
+- `ui/progress-bar` — `width: 40% !important` overrides the determinate width binding during the
+  indeterminate animation.
+
+---
+
+## Token reference
+
+The complete, current list of tokens (with default values) is the generated
+`@frame-kit/tokens` output — see `base.css` / `dark.css`, or the typed `tokens` object from
+the package root. Token _values_ are authored in `tokens/src/scss/tokens.base.scss`.

package/core/headline/README.md

@@ -0,0 +1,121 @@
+# fk-headline
+
+A heading component that renders semantic `h1`–`h6` elements with token-driven typography and optional visually hidden mode.
+
+---
+
+## API
+
+### Inputs
+
+| Input            | Type              | Default     | Description                                                             |
+| ---------------- | ----------------- | ----------- | ----------------------------------------------------------------------- |
+| `ariaLabel`      | `string \| null`  | `null`      | ARIA label when the visible text is not sufficient                      |
+| `className`      | `string`          | `''`        | Additional CSS classes for the host                                     |
+| `id`             | `string \| null`  | `null`      | Optional ID for the heading element                                     |
+| `level`          | `HeadlineLevel`   | `2`         | Heading level (`1`–`6`)                                                 |
+| `variant`        | `HeadlineVariant` | `"default"` | Visual variant (e.g. default, muted)                                    |
+| `visuallyHidden` | `boolean`         | `false`     | When `true`, hides the heading visually but keeps it for screen readers |
+
+Content is provided via projection:
+
+```html
+<fk-headline [level]="2">Section title</fk-headline>
+```
+
+---
+
+## Features
+
+- Renders proper semantic heading elements based on `level`
+- Token-driven typography for each heading level and variant
+- Visually hidden option for screen-reader-only headings
+- Dev-time warning when multiple `h1` elements are detected on a page
+
+---
+
+## Quick Start
+
+```html
+<fk-headline [level]="1"> Project dashboard </fk-headline>
+```
+
+---
+
+## Import
+
+```ts
+import { HeadlineComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [HeadlineComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-headline></fk-headline>
+```
+
+---
+
+## Examples
+
+### Heading hierarchy
+
+```html
+<fk-headline [level]="1">Dashboard</fk-headline>
+<fk-headline [level]="2">Open projects</fk-headline>
+<fk-headline [level]="3">Pending approvals</fk-headline>
+```
+
+### Muted variant
+
+```html
+<fk-headline [level]="4" variant="muted"> Optional details </fk-headline>
+```
+
+### Visually hidden heading
+
+```html
+<fk-headline [level]="2" [visuallyHidden]="true"> Recent activity </fk-headline>
+```
+
+---
+
+## Accessibility
+
+- Use `level` to maintain a logical heading order (only one `h1` per page is recommended).
+- When `visuallyHidden` is `true`, the heading remains in the accessibility tree while being visually hidden using a screen-reader-only utility class.
+- In dev mode, the component warns if multiple `h1` elements are detected, encouraging good document structure.
+
+---
+
+## Design Tokens
+
+`fk-headline` uses heading typography tokens such as:
+
+```scss
+--fk-headline-h1-font-size;
+--fk-headline-h2-font-size;
+--fk-headline-h3-font-size;
+--fk-headline-color;
+--fk-headline-muted-color;
+```
+
+Override in your theme as needed to match your brand type scale.
+
+---
+
+## Behavior Notes
+
+- `variant="muted"` adds a `fk-headline--muted` class, typically reducing contrast or emphasis.
+- When used as a visual-only heading (for example inside a card), choose an appropriate `level` relative to the surrounding document structure.

package/core/icon/README.md

@@ -0,0 +1,173 @@
+# fk-icon
+
+An SVG icon renderer for Angular that pulls icons from a shared registry and supports token-driven size and color.
+
+---
+
+## API
+
+### Inputs
+
+| Input        | Type                  | Default     | Description                                                                   |
+| ------------ | --------------------- | ----------- | ----------------------------------------------------------------------------- |
+| `name`       | `string` (required)   | —           | Icon name registered in `IconRegistryService`                                 |
+| `size`       | `IconSize \| string`  | `"md"`      | Preset size (`xs`–`xl`) or custom CSS size string (e.g. `"20px"`, `"1.5rem"`) |
+| `color`      | `IconColor \| string` | `"inherit"` | Color variant or custom CSS color value                                       |
+| `className`  | `string`              | `''`        | Additional CSS classes merged onto the host element                           |
+| `id`         | `string \| null`      | `null`      | Optional ID for the icon element                                              |
+| `ariaLabel`  | `string \| null`      | `null`      | Accessible label when the icon conveys meaning                                |
+| `ariaHidden` | `boolean \| null`     | `null`      | Explicit ARIA hidden flag; when `null`, derived from `ariaLabel`              |
+
+`size` supports named presets (`xs`, `sm`, `md`, `lg`, `xl`). Any other value is treated as a custom CSS `font-size`.
+
+### Outputs
+
+`fk-icon` is presentational and does not emit outputs.
+
+---
+
+## Features
+
+- Centralized SVG icon management via `IconRegistryService`
+- Size presets plus custom sizing via `size`
+- Color variants mapped to tokens, with support for custom CSS colors
+- Smart accessibility defaults (`aria-hidden` unless labeled)
+
+---
+
+## Quick Start
+
+\`\`\`ts
+constructor(private readonly iconRegistry: IconRegistryService) {
+this.iconRegistry.registerIcon("check", "<svg>...</svg>");
+}
+\`\`\`
+
+\`\`\`html
+<fk-icon name="check" color="success"></fk-icon>
+\`\`\`
+
+---
+
+## Import
+
+\`\`\`ts
+import { IconComponent } from "@frame-kit/ui-ng";
+\`\`\`
+
+\`\`\`ts
+@Component({
+selector: "app-example",
+imports: [IconComponent],
+templateUrl: "./example.component.html",
+})
+export class ExampleComponent {}
+\`\`\`
+
+---
+
+## Selector
+
+\`\`\`html
+<fk-icon></fk-icon>
+\`\`\`
+
+---
+
+## Examples
+
+### Size presets
+
+\`\`\`html
+<fk-icon name="home" size="xs"></fk-icon>
+<fk-icon name="home" size="sm"></fk-icon>
+<fk-icon name="home" size="md"></fk-icon>
+<fk-icon name="home" size="lg"></fk-icon>
+<fk-icon name="home" size="xl"></fk-icon>
+\`\`\`
+
+### Custom size
+
+\`\`\`html
+<fk-icon name="logo" size="32px"></fk-icon>
+<fk-icon name="logo" size="2rem"></fk-icon>
+\`\`\`
+
+### Color variants
+
+\`\`\`html
+<fk-icon name="info" color="default"></fk-icon>
+<fk-icon name="info" color="muted"></fk-icon>
+<fk-icon name="check-circle" color="success"></fk-icon>
+<fk-icon name="alert-circle" color="danger"></fk-icon>
+\`\`\`
+
+### Custom color
+
+\`\`\`html
+<fk-icon name="star" color="#facc15"></fk-icon>
+\`\`\`
+
+### Accessible icons
+
+\`\`\`html
+
+<!-- Decorative icon (hidden from screen readers) -->
+
+<fk-icon name="chevron-right"></fk-icon>
+
+<!-- Meaningful icon with label -->
+
+<fk-icon name="warning" ariaLabel="High priority"></fk-icon>
+\`\`\`
+
+---
+
+## Accessibility
+
+- If `ariaHidden` is `null` and `ariaLabel` is not provided, the icon is treated as decorative (`aria-hidden="true"`)
+- If `ariaLabel` is provided, the icon gets `role="img"` and `aria-hidden` is not applied
+- Use `ariaLabel` for standalone icons that convey meaning; leave it unset for purely decorative icons
+
+---
+
+## Design Tokens
+
+`fk-icon` uses icon tokens for presets and colors:
+
+\`\`\`scss
+--fk-icon-size-xs;
+--fk-icon-size-sm;
+--fk-icon-size-md;
+--fk-icon-size-lg;
+--fk-icon-size-xl;
+
+--fk-icon-color-default;
+--fk-icon-color-muted;
+--fk-icon-color-primary;
+--fk-icon-color-danger;
+--fk-icon-color-success;
+\`\`\`
+
+Override tokens in your application stylesheet:
+
+\`\`\`scss
+:root {
+--fk-icon-size-md: 1.25rem;
+}
+\`\`\`
+
+---
+
+## Behavior Notes
+
+- In dev mode, attempting to render a non-registered `name` logs a console warning
+- When `size` is not one of the presets, a custom `font-size` is applied via inline style
+
+---
+
+## Security
+
+`IconRegistryService.registerIcon` calls `bypassSecurityTrustHtml` on the SVG content it receives. The bypass is required: Angular's HTML sanitizer strips most SVG attributes that icons rely on, so the registry has to mark icons as trusted. The safety story rests on **every registered SVG originating from a build-time import** of an `.svg` file in `libs/icons/src/lib/icons/svg/**` — never from a runtime fetch and never from an inline string literal in a feature module.
+
+A repo-level guardrail enforces this: `libs/ui-ng/src/lib/core/icon/icon-registry.guardrail.spec.ts` walks every production TypeScript file under `apps/` and `libs/` and fails if it finds a `<svg` literal outside the icon library or the registry's own normalization regex. Any future caller that hand-rolls an SVG string trips the test.