@frame-kit/ui-ng 0.0.1

package/DEVELOPMENT_GUIDE.md

@@ -0,0 +1,1102 @@
+# FrameKit UI-ng — Component Development Guide
+
+This is the single source of truth for building components in `packages/ui-ng`. Follow every section exactly. If a pattern is defined here, it is non-negotiable. The goal is absolute consistency across every component in the library.
+
+---
+
+## Table of Contents
+
+1. [Architecture Overview](#architecture-overview)
+2. [Folder and File Structure](#folder-and-file-structure)
+3. [Component TypeScript](#component-typescript)
+4. [Templates](#templates)
+5. [Styling (SCSS)](#styling-scss)
+6. [Token Architecture](#token-architecture)
+7. [Dark Mode](#dark-mode)
+8. [Spacing Rules](#spacing-rules)
+9. [Directives](#directives)
+10. [Services](#services)
+11. [Types](#types)
+12. [Tests](#tests)
+13. [Storybook Stories](#storybook-stories)
+14. [README Documentation](#readme-documentation)
+15. [Public API Exports](#public-api-exports)
+16. [Accessibility](#accessibility)
+17. [Definition of Done](#definition-of-done)
+
+---
+
+## Architecture Overview
+
+FrameKit UI-ng is a style-agnostic, token-driven Angular component library. Components define structure, layout, accessibility, and interaction. They never define brand styling. All visual decisions come from `--fk-*` design tokens provided by the consumer application.
+
+### Core principles
+
+1. **Components never contain brand styling.** No hardcoded colors, typography scales, brand radii, shadows, or visual identity. All visual styling is expressed via CSS custom properties.
+2. **Components only consume tokens.** Token definitions belong in theme files, never in component SCSS.
+3. **Components are self-sufficient.** Every component renders correctly with zero external dependencies — no theme file required.
+4. **Stable public API.** Consumers use `<fk-*>` components with stable inputs. Internal implementations can change without breaking consumers.
+
+### Library structure
+
+Components are organized by **purpose**, not Atomic Design. Each layer has clear responsibilities and a strict dependency direction:
+
+```
+packages/ui-ng/
+  index.ts       — primary barrel; re-exports every entry point as @frame-kit/ui-ng
+  core/          — raw primitives, no other lib component deps (icon, text, headline, link, image, separator)
+  ui/            — composed reusable UI (button, dialog, drawer, toast, tabs, data-table, etc.)
+  directives/    — standalone behavior directives (tooltip, infinite-scroll, spotlight)
+  docs/          — API-reference UI (endpoint-link, method-badge)
+  forms/         — self-contained form system; packaged as ONE entry point (holds its own primitives)
+    engine/      — schema parser, field registry, validation, error messages, field state
+    fields/      — 16 form-field components (input, select, checkbox, etc.)
+    composition/ — form wrappers and renderer (form, form-field, form-renderer, label, hint, error, etc.)
+  layouts/       — structural page scaffolding (app-shell, content-split)
+  services/      — runtime services with no UI (overlay-orchestrator, toast, spotlight)
+```
+
+> Color/date helpers are **not** in this library — they live in `@frame-kit/utils` (framework-agnostic `Color` / `DateUtil`). Don't add UI-less utility services here that have no Angular dependency.
+
+**Dependency rules:**
+
+- `core` imports nothing from the lib.
+- `ui`, `directives`, and `docs` may use `core` and `services`.
+- `forms` may use `core`, `ui`, `directives`, and `services`.
+- `layouts` may use anything; nothing imports from `layouts`.
+
+All layers follow the same conventions defined in this guide.
+
+### Packaging: secondary entry points
+
+The library is published with **one ng-packagr secondary entry point per component** so consumers can tree-shake and code-split per component. This shapes how source is laid out and how components import each other:
+
+- **Each leaf component folder is its own entry point** — `packages/ui-ng/<layer>/<name>/` builds to `@frame-kit/ui-ng/<layer>/<name>` (its own FESM). The one exception is **`forms/`**, which is a single entry point (`@frame-kit/ui-ng/forms`) because `engine`/`fields`/`composition` are mutually dependent — its sub-folders are **not** separate entry points.
+- **The primary `index.ts` barrel** re-exports every entry point, so consumers keep importing from `@frame-kit/ui-ng` and still get per-component splitting.
+- **Cross-component imports must use the package path, not a relative `../`.** ng-packagr forbids relative imports that cross an entry-point boundary. Import a sibling component via its entry point:
+
+  ```ts
+  // ✅ in ui/button — importing the loader (a different entry point)
+  import { LoaderComponent } from '@frame-kit/ui-ng/ui/loader';
+
+  // ❌ crosses an entry-point boundary — ng-packagr build fails
+  import { LoaderComponent } from '../loader/loader.component';
+  ```
+
+  Imports **within the same entry point stay relative** (e.g. a forms field importing `../../engine/schema`, or a component importing its own `./button.types`).
+
+See [Public API Exports](#public-api-exports) for the files each new component must add.
+
+### Token layers
+
+| Layer                    | Location                                    | Purpose                                                           |
+| ------------------------ | ------------------------------------------- | ----------------------------------------------------------------- |
+| 1. Component consumption | `packages/ui-ng/**/*.scss`                  | Consumes `--fk-*` tokens with two-tier fallbacks                  |
+| 2. Base tokens           | `packages/tokens/src/scss/tokens.base.scss` | Default theme opinion — maps semantic tokens to component tokens  |
+| 3. Dark mode             | `packages/tokens/src/scss/tokens.dark.scss` | Remaps color-sensitive tokens for dark mode                       |
+| 4. Consumer overrides    | Consumer app stylesheets                    | Consumers override tokens at `:root`, `.theme-*`, or per-instance |
+
+---
+
+## Folder and File Structure
+
+Every component must have this exact file set, placed in the correct layer (`core/`, `ui/`, `directives/`, `docs/`, `forms/{engine,fields,composition}/`, `layouts/`):
+
+```
+packages/ui-ng/<layer>/<name>/
+  <name>.component.ts
+  <name>.component.html
+  <name>.component.scss
+  <name>.component.spec.ts
+  <name>.component.stories.ts
+  <name>.types.ts
+  README.md
+  index.ts                          (entry-point barrel — see note below)
+  ng-package.json                   (entry-point marker — see note below)
+```
+
+`index.ts` and `ng-package.json` make the folder a secondary entry point. Their contents are fixed boilerplate:
+
+```ts
+// index.ts — export the component's public files
+export * from './<name>.component';
+export * from './<name>.types';
+// + any associated directives, e.g. export * from './<name>-icon.directive';
+```
+
+```json
+// ng-package.json
+{ "lib": { "entryFile": "index.ts" } }
+```
+
+**Exception — `forms/`:** components under `forms/{engine,fields,composition}/<name>/` do **not** get their own `index.ts`/`ng-package.json`. Forms is a single entry point: add the component's public files to the relevant sub-barrel (`forms/composition/index.ts`, `forms/fields/index.ts`, or `forms/engine/index.ts`) instead.
+
+Additional files when the component uses content projection directives:
+
+```
+  <name>-<slot>.directive.ts        (e.g. alert-icon.directive.ts)
+```
+
+### Naming conventions
+
+- Folder name: kebab-case matching the component name (`badge`, `inline-edit`, `data-table`)
+- File names: always `<folder-name>.component.*`
+- Types file: always `<folder-name>.types.ts`
+- Directive files: `<folder-name>-<purpose>.directive.ts`
+
+---
+
+## Component TypeScript
+
+### Required structure
+
+Every component follows this exact pattern. Reference the badge component as the canonical atom example and the alert component as the canonical molecule example.
+
+```ts
+import { ChangeDetectionStrategy, Component, HostBinding, computed, input } from '@angular/core';
+
+import type { ExampleVariant } from './example.types';
+
+@Component({
+  selector: 'fk-example',
+  standalone: true,
+  imports: [],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  templateUrl: './example.component.html',
+  styleUrl: './example.component.scss',
+})
+export class ExampleComponent {
+  // ===== INPUTS =====
+  readonly variant = input<ExampleVariant>('default');
+
+  // ===== CONTENT CHILDREN =====
+  // (only when component uses content projection directives)
+
+  // ===== BASE PROPS =====
+  readonly className = input<string>('');
+  readonly id = input<string | null>(null);
+  readonly ariaLabel = input<string | null>(null);
+
+  // ===== COMPUTED =====
+  readonly classes = computed(() => {
+    return ['fk-example', `fk-example--${this.variant()}`, this.className()].filter(Boolean).join(' ');
+  });
+
+  @HostBinding('class')
+  get hostClass() {
+    return this.classes();
+  }
+}
+```
+
+### Rules
+
+- **Always standalone.** Every component sets `standalone: true`.
+- **Always OnPush.** Every component uses `ChangeDetectionStrategy.OnPush`.
+- **Signal-based inputs.** Use Angular's `input<Type>(default)` API. Never use the `@Input()` decorator.
+- **Selector prefix.** Always `fk-` followed by the component name in kebab-case.
+- **Section comments.** Organize the class body with `// ===== SECTION =====` dividers in this order: INPUTS, CONTENT CHILDREN, BASE PROPS, COMPUTED.
+
+### Base props convention
+
+All components should support these inputs when relevant:
+
+- `className?: string` — additional CSS classes merged onto the host (default: `""`)
+- `id?: string | null` — optional ID (default: `null`)
+- `ariaLabel?: string | null` — accessible label (default: `null`)
+- `ariaDescribedBy?: string | null` — ID of describing element (default: `null`)
+- `disabled?: boolean` — disables interaction (default: `false`)
+
+### Host class binding
+
+All components must use this unified mechanism:
+
+1. Compute a `classes` signal combining base class + modifiers + consumer `className`
+2. Bind to host via `@HostBinding("class")` getter that returns `this.classes()`
+3. Base class is always `fk-<name>`
+4. Modifier classes follow BEM: `fk-<name>--<modifier>`
+
+**Do NOT use:**
+
+- `host: { "[class]": ... }` in the `@Component` decorator
+- Multiple class systems in one component
+- Binding classes only to inner elements instead of the host
+
+### Semantic variants
+
+Variants and sizes must be semantic, library-owned values:
+
+- `variant: "primary" | "secondary" | "danger"` — not vendor-specific names
+- `size: "sm" | "md" | "lg"` — not pixel values
+
+---
+
+## Templates
+
+### Content projection
+
+Use `<ng-content />` for default slot projection:
+
+```html
+<ng-content />
+```
+
+For named slots, use attribute selectors matching directive selectors:
+
+```html
+<ng-content select="[fkAlertIconStart]" />
+<span class="fk-alert__content">
+  <ng-content />
+</span>
+```
+
+### ID and ARIA binding
+
+Pass base props through to the appropriate element in the template:
+
+```html
+<span [id]="id() ?? undefined" [attr.aria-label]="ariaLabel()">
+  <ng-content />
+</span>
+```
+
+### Self-closing syntax
+
+Use self-closing tags for void elements:
+
+```html
+<ng-content /> <router-outlet />
+```
+
+---
+
+## Styling (SCSS)
+
+### Host element styling
+
+Style the host element directly with `:host`:
+
+```scss
+:host {
+  display: inline-flex;
+  align-items: center;
+  height: var(--fk-badge-height, 1.5rem);
+  border-radius: var(--fk-badge-border-radius, 999px);
+  font-size: var(--fk-badge-font-size, 0.75rem);
+  font-weight: var(--fk-badge-font-weight, var(--fk-font-weight-medium, 500));
+}
+```
+
+### Variant styles
+
+Apply variant styles using the host class + variant modifier:
+
+```scss
+:host.fk-badge--primary {
+  background-color: var(--fk-badge-primary-bg, var(--fk-color-primary-subtle, #e8f4ff));
+  color: var(--fk-badge-primary-color, var(--fk-color-primary, #0a84ff));
+}
+```
+
+### BEM naming for internal elements
+
+Internal elements use BEM naming under the component namespace:
+
+```scss
+.fk-alert__content {
+  flex: 1;
+}
+
+.fk-inline-edit__input { ... }
+.fk-inline-edit__action--save { ... }
+```
+
+### Section comments in SCSS
+
+Use section dividers for readability:
+
+```scss
+// ===== VARIANT COLORS =====
+```
+
+### What component SCSS must do
+
+- Consume tokens with `var(--fk-*)` using the two-tier fallback pattern (see [Token Architecture](#token-architecture))
+- Use hook classes: `fk-<name>` + modifiers like `fk-<name>--primary`
+- Work correctly with `tokens.base.scss` loaded
+- Work correctly with NO theme file loaded (via fallback values)
+
+### What component SCSS must NEVER do
+
+- **Define `--fk-*` tokens.** Token definitions belong only in theme files (`tokens.base.scss`, `tokens.dark.scss`), never in component SCSS.
+- **Use `::ng-deep`.** Find an alternative approach.
+- **Hardcode hex colors as primary values.** Hex is only allowed as the last-resort fallback inside `var()`.
+- **Use `margin-bottom` for spacing between siblings.** See [Spacing Rules](#spacing-rules).
+
+---
+
+## Token Architecture
+
+### The two-tier fallback pattern (required)
+
+Every token reference in component SCSS must include a fallback chain so the component renders correctly even when no theme file is loaded:
+
+```scss
+/* ✅ Correct — two-tier fallback */
+padding: var(--fk-callout-padding, var(--fk-rhythm-4, 1rem));
+background-color: var(--fk-callout-bg, var(--fk-color-surface-muted, #f7f9fb));
+
+/* ❌ Wrong — no fallback, breaks without theme */
+padding: var(--fk-callout-padding);
+```
+
+The fallback chain is:
+
+1. **Component token** (`--fk-callout-padding`) — the consumer override point
+2. **Semantic token** (`--fk-rhythm-4`) — picks up the global theme if loaded
+3. **Raw value** (`1rem`) — the hardcoded baseline that always works
+
+This guarantees components are never visually broken regardless of which theme layers are present.
+
+### Token naming
+
+All tokens are prefixed with `--fk-*`. Component-specific tokens follow the pattern:
+
+```
+--fk-<component>-<property>
+--fk-<component>-<variant>-<property>
+```
+
+Examples:
+
+```
+--fk-badge-height
+--fk-badge-font-size
+--fk-badge-primary-bg
+--fk-badge-primary-color
+--fk-alert-padding
+--fk-alert-info-bg
+--fk-alert-info-color
+```
+
+Semantic tokens (shared across components):
+
+```
+--fk-color-primary
+--fk-color-surface-muted
+--fk-color-text
+--fk-font-weight-medium
+--fk-rhythm-4
+--fk-radius-md
+--fk-focus-ring
+```
+
+### Where tokens are defined
+
+Tokens are defined ONLY in theme files, NEVER in component SCSS:
+
+| File                                        | What it defines               |
+| ------------------------------------------- | ----------------------------- |
+| `packages/tokens/src/scss/tokens.base.scss` | All token defaults in `:root` |
+| `packages/tokens/src/scss/tokens.dark.scss` | Dark mode color overrides     |
+
+Token definitions must only appear in:
+
+- `:root`
+- `.theme-*`
+
+Token definitions must NEVER appear in:
+
+- `.fk-*` selectors
+- `:host`
+- Component selectors
+
+This ensures consumer overrides always win — component selectors would increase specificity and break the override chain.
+
+### Adding tokens for a new component
+
+1. Define component tokens in `tokens.base.scss` following the ITCSS order (primitives, semantic, component tokens grouped by layer: core, ui, directives, forms, layouts, keyframes)
+2. If the component has color-sensitive tokens, add dark mode overrides in `tokens.dark.scss` under both the `@media (prefers-color-scheme: dark)` block and the `html.dark` block
+3. Document the tokens in the component README
+
+---
+
+## Dark Mode
+
+### How it works
+
+Dark mode is a token remapping layer. Components are completely unaware of dark mode — they consume the same `--fk-*` tokens regardless of theme. The dark mode file (`tokens.dark.scss`) redefines color-sensitive tokens under two selectors:
+
+1. `@media (prefers-color-scheme: dark)` — system preference, automatic
+2. `html.dark` — user override via JavaScript, always wins due to higher specificity
+
+### What gets remapped in dark mode
+
+Only color-sensitive tokens:
+
+- Color primitives (`--fk-color-surface`, `--fk-color-text`, `--fk-color-border`, etc.)
+- Focus ring (`--fk-focus-ring`)
+- Component color tokens (backgrounds, text colors, border colors)
+
+### What stays the same
+
+Non-color tokens are NOT redefined:
+
+- Typography (font sizes, weights, line heights)
+- Spacing / rhythm
+- Radii
+- Sizing tokens
+
+### Adding dark mode support for a new component
+
+When your component introduces new color tokens, add overrides in `tokens.dark.scss` under both blocks:
+
+```scss
+@media (prefers-color-scheme: dark) {
+  :root {
+    --fk-newcomponent-bg: var(--fk-color-surface-muted);
+    --fk-newcomponent-color: var(--fk-color-text);
+  }
+}
+
+html.dark {
+  --fk-newcomponent-bg: var(--fk-color-surface-muted);
+  --fk-newcomponent-color: var(--fk-color-text);
+}
+```
+
+### Verification
+
+Always verify appearance in both light and dark modes. Run Storybook (it loads `tokens.base.scss` + `tokens.dark.scss`) and toggle the theme:
+
+```bash
+npm run storybook:ui-ng
+```
+
+---
+
+## Spacing Rules
+
+### Margin direction convention
+
+Use **top margin only** for vertical spacing between elements. Bottom margin is always zero.
+
+This matches the token definitions:
+
+```scss
+--fk-text-margin-block-start: var(--fk-rhythm-4); /* top */
+--fk-text-margin-block-end: 0; /* bottom */
+--fk-headline-margin-block-start: var(--fk-rhythm-4);
+--fk-headline-margin-block-end: 0;
+```
+
+### Rules
+
+- Space between elements is created by the **top margin of the next element**, not the bottom margin of the current element
+- Never use `margin-bottom` for spacing between siblings
+- Prefer `gap` (via flex/grid) over directional margins when elements are in a flex or grid container
+- Micro-alignment nudges (e.g. `margin-top: 0.125rem` to align an icon with text) are acceptable
+
+### Examples
+
+```scss
+/* ✅ Correct — gap-based spacing */
+.container {
+  display: flex;
+  flex-direction: column;
+  gap: var(--fk-rhythm-3, 0.75rem);
+}
+
+/* ✅ Correct — top margin */
+.next-element {
+  margin-top: var(--fk-rhythm-4, 1rem);
+}
+
+/* ❌ Wrong — bottom margin for spacing */
+.current-element {
+  margin-bottom: var(--fk-rhythm-4, 1rem);
+}
+```
+
+### Field-level vs container-level spacing
+
+For atom-tier components — anything in `forms/fields/` (`fk-input`, `fk-textarea`, `fk-select`, etc.) and the `fk-form-field` wrapper — **do not put margin on the host**. Inter-field rhythm is owned by parent containers (`fk-field-group`, `fk-form-renderer__fields`, or any consumer-supplied `display: flex; flex-direction: column; gap: var(--fk-form-field-gap, …)` wrapper).
+
+Why this matters: the `:host { margin-top: ... } / :host:first-child { margin-top: 0 }` pattern fires per-parent, not per-form. When fields are wrapped (e.g. each `fk-form-field` sits inside its own `fk-field-outlet` in the schema-driven path), every wrapped field matches `:first-child` and zeros its margin — so the form ends up flush. When fields are direct siblings of a `<form>` element (the manual path), only the literal first sibling matches the reset and the rest carry full margin. The result is two visually different forms even though the components and validators are identical.
+
+```scss
+/* ❌ Wrong — host-driven inter-field rhythm */
+:host {
+  margin-top: var(--fk-form-field-gap, var(--fk-rhythm-4, 1rem));
+}
+:host:first-child {
+  margin-top: 0;
+}
+
+/* ✅ Correct — parent-driven inter-field rhythm */
+/* In the parent (fk-field-group, fk-form-renderer, etc.): */
+.fk-field-group__content {
+  display: flex;
+  flex-direction: column;
+  row-gap: var(--fk-form-field-gap, var(--fk-rhythm-4, 1rem));
+}
+```
+
+The Storybook regression test for this pattern lives at `Forms/Composition/Form Renderer · SpacingParity` — a side-by-side comparison of a schema-rendered form and a hand-built form with identical fields. They should render pixel-identical; if they ever drift, host-margin has crept back into a field somewhere.
+
+---
+
+## Directives
+
+There are two distinct directive kinds in this library — they look similar in code but have different purposes and different documentation requirements.
+
+| Kind                        | Lives in                                             | Has its own README?                         | Has stories?      |
+| --------------------------- | ---------------------------------------------------- | ------------------------------------------- | ----------------- |
+| **Behavior directives**     | `packages/ui-ng/directives/`                         | Yes — full per-kind README (see below)      | Yes               |
+| **Content-slot directives** | Inside the parent component's folder (e.g. `alert/`) | No — covered in the parent component's docs | No (no UI on own) |
+
+### Behavior directives
+
+Standalone directives that add behavior to any element they're applied to (e.g. `fkTooltip`, `fkInfiniteScroll`, `fkSpotlightTrigger`). Each lives in its own folder under `packages/ui-ng/directives/<name>/` and ships its own README + Storybook story alongside the source.
+
+#### Required files
+
+```
+packages/ui-ng/directives/<name>/
+  <name>.directive.ts
+  <name>.directive.spec.ts
+  <name>.directive.stories.ts
+  README.md
+  index.ts                          (entry-point barrel: export * from './<name>.directive')
+  ng-package.json                   ({ "lib": { "entryFile": "index.ts" } })
+```
+
+A behavior directive is its own secondary entry point (`@frame-kit/ui-ng/directives/<name>`). When the directive needs companion utilities (positioning helpers, types files), keep them in the same folder and export them from `index.ts`; the README points at the public surface.
+
+#### README section order
+
+Mirrors the component README order so consumers don't have to re-learn structure:
+
+1. **Title + one-line summary** — `# fkTooltip` followed by a sentence describing what the directive does and where it attaches.
+2. **API** — Inputs (table), Outputs (table or "None."), and a Types subsection if the directive exposes string-literal types.
+3. **Features** — short bullet list.
+4. **Quick Start** — smallest useful HTML snippet using the attribute.
+5. **Import** — `@frame-kit/ui-ng` import + standalone `imports: [...]` registration.
+6. **Examples** — one subsection per realistic usage pattern.
+7. **Accessibility** — keyboard behavior, ARIA host bindings, focus interaction, `prefers-reduced-motion` handling, anti-patterns.
+8. **Design Tokens** (when the directive renders any styled UI like a tooltip popover) — tokens consumed + override snippet.
+9. **Behavior Notes** — edge cases, lifecycle (when host is destroyed), and how the directive interacts with the `OverlayOrchestrator` if it owns an overlay.
+
+#### Storybook coverage
+
+- Default usage attached to a single host element.
+- One story per non-trivial input variant (e.g. each `position` for `fkTooltip`).
+- An `AllVariants` composite when the directive has more than two configuration knobs, so the gallery shows them side-by-side.
+- For directive pairs that only make sense together (e.g. `fkSpotlightTrigger` + `fkSpotlightTarget`), one story may suffice — render both in the same fixture.
+
+#### JSDoc on the public API
+
+Every `input()`, `output()`, `model()`, and public method on the directive class carries a one-line JSDoc above its declaration. Inputs answer "what does this control?", outputs "when does this fire?", methods "what does this do?". The class itself carries a paragraph-level JSDoc explaining the directive's responsibility (one short paragraph; no marketing copy).
+
+### Content-slot directives
+
+When a component needs named content slots (e.g. an icon slot in an alert), create a marker directive:
+
+```ts
+import { Directive, InjectionToken } from '@angular/core';
+
+export const FK_ALERT_ICON_START = new InjectionToken<FkAlertIconStartDirective>('FK_ALERT_ICON_START');
+
+@Directive({
+  selector: '[fkAlertIconStart]',
+  standalone: true,
+  providers: [{ provide: FK_ALERT_ICON_START, useExisting: FkAlertIconStartDirective }],
+  host: {
+    'aria-hidden': 'true',
+  },
+})
+export class FkAlertIconStartDirective {}
+```
+
+#### Rules
+
+- Directive selector is always a camelCase attribute: `[fkComponentSlotName]`
+- Provide an `InjectionToken` so the parent component can detect the directive via `contentChild()`
+- Set appropriate `host` attributes (e.g. `aria-hidden` for decorative icons)
+- Directive is always `standalone: true`
+- The parent component detects the directive using `contentChild(FK_TOKEN_NAME)`:
+
+```ts
+readonly iconStartRef = contentChild(FK_ALERT_ICON_START);
+```
+
+#### Naming conventions
+
+- InjectionToken constant: `FK_<COMPONENT>_<SLOT>` (screaming snake case)
+- Directive class: `Fk<Component><Slot>Directive` (PascalCase)
+- Selector attribute: `fk<Component><Slot>` (camelCase)
+
+---
+
+## Services
+
+Runtime services with no UI that **depend on Angular** (e.g. `OverlayOrchestrator`, `ToastService`, `SpotlightService`). Each lives in its own folder under `packages/ui-ng/services/<name>/` and ships a README alongside the source. Framework-agnostic helpers (color, date math) do **not** belong here — they go in `@frame-kit/utils`.
+
+### Required files
+
+```
+packages/ui-ng/services/<name>/
+  <name>.service.ts
+  <name>.service.spec.ts
+  README.md
+  index.ts                          (entry-point barrel: export * from './<name>.service')
+  ng-package.json                   ({ "lib": { "entryFile": "index.ts" } })
+```
+
+A service is its own secondary entry point (`@frame-kit/ui-ng/services/<name>`). Services do not ship Storybook stories — they have no rendered surface. Behavior is exercised through their unit spec.
+
+### Provider scope
+
+State the provider scope at the top of the README. Two patterns:
+
+- **Root-provided** (`@Injectable({ providedIn: "root" })`) — singleton across the app. Default for orchestration, registries, and global mutable state. Document any side effects of construction (subscriptions, listeners) so consumers know what they're opting into.
+- **Component-tree-provided** — when the service must be scoped to a feature (e.g. one toast queue per overlay surface). The README must show where to declare the provider.
+
+### README section order
+
+1. **Title + one-line summary** — `# OverlayOrchestrator` followed by a sentence stating the service's responsibility.
+2. **Initialization** — provider scope, any setup required, and (if applicable) any built-in integrations the service triggers automatically.
+3. **API** — Public methods and signals as a table or sub-sections. For each: signature, return type, what it does, when to call it, what it emits/mutates.
+4. **Usage** — A realistic snippet wiring the service into a component (`inject(...)`, calling the method, reading the signal).
+5. **Behavior Notes** — Concurrency contract, lifecycle (when handles are released), interaction with other services (e.g. how `DialogService` registers with `OverlayOrchestrator`).
+
+Services typically don't have Accessibility or Design Tokens sections. Skip them rather than leaving them empty. If the service exposes a value object that ships with token-driven defaults (e.g. a default toast variant), document that in Behavior Notes.
+
+### JSDoc on the public API
+
+Every public method, signal, and exported constant on the service carries a one-line JSDoc above its declaration. The class itself carries a paragraph-level JSDoc explaining the service's responsibility and the singleton vs scoped contract.
+
+---
+
+## Types
+
+Every component has a `<name>.types.ts` file that exports its variant and configuration types:
+
+```ts
+export type BadgeVariant = 'default' | 'primary' | 'success' | 'warning' | 'danger';
+```
+
+### Rules
+
+- One types file per component
+- Export union types for variants, sizes, and any string-literal inputs
+- Import types with `import type { ... }` in the component file
+- Keep types minimal — only what the public API needs
+
+---
+
+## Tests
+
+### Required test file structure
+
+```ts
+import { Component } from "@angular/core";
+import { ComponentFixture, TestBed } from "@angular/core/testing";
+import { ExampleComponent } from "./example.component";
+
+describe("ExampleComponent", () => {
+  let component: ExampleComponent;
+  let fixture: ComponentFixture<ExampleComponent>;
+
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [ExampleComponent],
+    }).compileComponents();
+
+    fixture = TestBed.createComponent(ExampleComponent);
+    component = fixture.componentInstance;
+    fixture.detectChanges();
+  });
+
+  it("should create", () => {
+    expect(component).toBeTruthy();
+  });
+
+  describe("Defaults", () => { ... });
+  describe("Host classes", () => { ... });
+  describe("Variants", () => { ... });
+  describe("Style overrides", () => { ... });
+  describe("Content projection", () => { ... });
+  describe("Base props passthrough", () => { ... });
+});
+```
+
+### Required test sections
+
+Every component spec must include these `describe` blocks:
+
+1. **`should create`** — basic instantiation check
+2. **`Defaults`** — verify every input's default value using `component.inputName()`
+3. **`Host classes`** — verify base class is applied, variant class is applied, variant class updates when input changes, custom `className` is merged without replacing hook classes
+4. **`Variants`** — iterate all variant values and verify each applies the correct class
+5. **`Style overrides`** — verify inline style bindings (color, backgroundColor, etc.) when applicable
+6. **`Content projection`** — create a test host component with projected content and verify it renders
+7. **`Base props passthrough`** — verify `id`, `ariaLabel`, etc. are passed through to the correct DOM element
+
+### Testing patterns
+
+- Use `fixture.componentRef.setInput("name", value)` to set signal-based inputs
+- For content projection tests, create an inline `@Component` test host:
+
+```ts
+@Component({
+  standalone: true,
+  imports: [BadgeComponent],
+  template: `<fk-badge>Active</fk-badge>`,
+})
+class TestHostComponent {}
+
+const hostFixture = TestBed.createComponent(TestHostComponent);
+hostFixture.detectChanges();
+```
+
+- Access the native element with `fixture.nativeElement as HTMLElement`
+- Check classes with `el.classList.contains("fk-badge")`
+- Check attributes with `el.getAttribute("aria-label")`
+- Check inline styles with `el.style.color`
+
+---
+
+## Storybook Stories
+
+### Required file structure
+
+```ts
+import type { Meta, StoryObj } from '@storybook/angular';
+import { ExampleComponent } from './example.component';
+
+const meta: Meta<ExampleComponent> = {
+  title: 'Atoms/Example', // or "Molecules/Example" or "Organisms/Example"
+  component: ExampleComponent,
+  tags: ['autodocs'],
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['default', 'primary', 'success', 'warning', 'danger'],
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<ExampleComponent>;
+```
+
+### Title convention
+
+- Atoms: `"Atoms/<Name>"`
+- Molecules: `"Molecules/<Name>"`
+- Organisms: `"Organisms/<Name>"`
+
+### Story pattern
+
+Each story uses a render function with props and template:
+
+```ts
+export const Default: Story = {
+  render: (args) => ({
+    props: args,
+    template: `<fk-example [variant]="variant">Content</fk-example>`,
+  }),
+  args: {
+    variant: 'default',
+  },
+};
+```
+
+### Required stories
+
+Every component must include stories for:
+
+- Default state
+- Each variant
+- Each size (if applicable)
+- Disabled state (if applicable)
+- Loading state (if applicable)
+- An `AllVariants` story showing all variants side by side
+- Accessibility example (if the component has ARIA considerations)
+
+### When using other components or directives
+
+Use `moduleMetadata` and `applicationConfig` decorators:
+
+```ts
+decorators: [
+  moduleMetadata({
+    imports: [IconComponent, FkAlertIconStartDirective],
+  }),
+  applicationConfig({
+    providers: [
+      provideIcons({
+        "shield-alert": shieldAlert,
+      }),
+    ],
+  }),
+],
+```
+
+### Storybook theming
+
+The `ui-ng` Storybook target loads `packages/tokens/src/scss/tokens.base.scss` and `tokens.dark.scss` (configured in `project.json`), so components render with the **default `@frame-kit/tokens` theme** applied — the same opinion a consumer gets out of the box. To sanity-check the no-theme baseline (fallback values only), temporarily remove those entries from the storybook `styles` array; every component must still render correctly because every token reference carries a two-tier fallback.
+
+---
+
+## README Documentation
+
+Every component must have a `README.md` following this exact section order. Do not skip sections. Do not reorder.
+
+### 1. Title + One-Line Summary
+
+```markdown
+# fk-example
+
+A token-driven example component for [describe primary use case].
+```
+
+### 2. API
+
+Break into subsections:
+
+- **Inputs** — table with Input, Type, Default, Description columns
+- **Outputs** — table with Output, Type, Description columns (or "None." if no outputs)
+- **Content** — describe projection slots with code example
+
+```markdown
+## API
+
+### Inputs
+
+| Input       | Type           | Default     | Description                    |
+| ----------- | -------------- | ----------- | ------------------------------ |
+| `variant`   | `BadgeVariant` | `"default"` | Visual style of the badge      |
+| `className` | `string`       | `''`        | Additional CSS classes on host |
+
+### Outputs
+
+None.
+
+### Content
+
+`fk-badge` projects its content:
+
+\`\`\`html
+<fk-badge>New</fk-badge>
+\`\`\`
+```
+
+### 3. Features
+
+Short bullet list of capabilities.
+
+### 4. Quick Start
+
+The smallest useful example.
+
+### 5. Import
+
+Show import path and component registration:
+
+```markdown
+## Import
+
+\`\`\`ts
+import { BadgeComponent } from "@frame-kit/ui-ng";
+\`\`\`
+
+\`\`\`ts
+@Component({
+selector: "app-example",
+imports: [BadgeComponent],
+templateUrl: "./example.component.html",
+})
+export class ExampleComponent {}
+\`\`\`
+```
+
+The import path is always `@frame-kit/ui-ng`.
+
+### 6. Selector
+
+Show the element selector.
+
+### 7. Examples
+
+One subsection per variant or use case with code blocks.
+
+### 8. Accessibility
+
+Document semantic element, keyboard behavior, ARIA attributes, disabled behavior, recommendations and anti-patterns.
+
+### 9. Design Tokens
+
+List the tokens the component consumes. Show how to override them:
+
+```markdown
+## Design Tokens
+
+\`\`\`scss
+--fk-badge-font-size
+--fk-badge-primary-bg
+--fk-badge-primary-color
+\`\`\`
+
+Override in your app stylesheet:
+
+\`\`\`scss
+:root {
+--fk-badge-radius: 9999px;
+}
+\`\`\`
+```
+
+### 10. Behavior Notes
+
+Edge cases, default behaviors, and recommendations. Keep short.
+
+---
+
+## Public API Exports
+
+There are two levels of barrel: the component's own entry-point `index.ts`, and the primary `index.ts` that aggregates all entry points.
+
+### Adding a new component to the public API
+
+For a component in `core/ui/directives/docs/layouts/services` (its own entry point):
+
+1. **Write the entry-point `index.ts`** in the component folder, exporting its public files:
+
+   ```ts
+   export * from './<name>.component';
+   export * from './<name>.types';
+   // + associated directives
+   ```
+
+2. **Add `ng-package.json`** in the same folder: `{ "lib": { "entryFile": "index.ts" } }`.
+
+3. **Add one line to the primary `packages/ui-ng/index.ts`**, re-exporting the new entry point so it's reachable via the `@frame-kit/ui-ng` barrel:
+
+   ```ts
+   export * from '@frame-kit/ui-ng/<layer>/<name>';
+   ```
+
+For a component under `forms/` (part of the single `forms` entry point): skip steps 1–3. Instead add its public files to the relevant sub-barrel (`forms/composition/index.ts`, `forms/fields/index.ts`, or `forms/engine/index.ts`). The primary barrel already re-exports `@frame-kit/ui-ng/forms`.
+
+ng-packagr discovers entry points by globbing for `ng-package.json`, so once the two files exist the new entry point is built automatically — no other config changes needed.
+
+### What to export (from the entry-point `index.ts`)
+
+- The component class
+- The types file
+- Any directives associated with the component
+
+### What NOT to export
+
+- Internal utilities or helpers
+- Test fixtures
+- Storybook stories
+
+---
+
+## Accessibility
+
+### Required for every component
+
+- Use semantic HTML elements (`button`, `a`, headings, `nav`, `dialog`)
+- Support `ariaLabel` and `ariaDescribedBy` inputs
+- Use tokenized focus styles via `--fk-focus-ring`
+- Apply `disabled` or `aria-disabled` correctly
+- Ensure keyboard navigation works (Enter, Space, Escape, Tab as appropriate)
+- Mark decorative elements as `aria-hidden="true"` (typically via directive host binding)
+
+### Focus styling
+
+All focusable elements must use the shared focus ring token:
+
+```scss
+&:focus-visible {
+  outline: none;
+  box-shadow: var(--fk-focus-ring, 0 0 0 3px rgba(10, 132, 255, 0.18));
+}
+```
+
+---
+
+## Definition of Done
+
+Before a component can be merged, every item must be checked:
+
+### Structure
+
+- [ ] Placed in the correct layer (`core/`, `ui/`, `directives/`, `docs/`, `forms/{engine,fields,composition}/`, or `layouts/`) following the dependency rules
+- [ ] All required files present (`.ts`, `.html`, `.scss`, `.spec.ts`, `.stories.ts`, `.types.ts`, `README.md`)
+- [ ] Entry-point files present (`index.ts` + `ng-package.json`) — for non-`forms` layers; `forms` components are added to the forms sub-barrels instead
+- [ ] Cross-component imports use the `@frame-kit/ui-ng/<layer>/<name>` package path, never a relative `../` across an entry-point boundary
+
+### Component
+
+- [ ] `standalone: true`
+- [ ] `ChangeDetectionStrategy.OnPush`
+- [ ] Signal-based inputs with `input<Type>(default)`
+- [ ] `@HostBinding("class")` with computed classes pattern
+- [ ] Consumer `className` merged without replacing hook classes
+- [ ] Base class `fk-<name>` and modifier classes `fk-<name>--<modifier>`
+
+### Styling
+
+- [ ] Consumes only `--fk-*` tokens
+- [ ] Two-tier fallback on every token reference
+- [ ] No `::ng-deep`
+- [ ] No token definitions in component SCSS
+- [ ] No hardcoded hex colors as primary values
+- [ ] Top-margin-only spacing convention followed
+- [ ] No host margin on field-level components — wrap consumers in a flex/grid container and use `gap` instead (see "Field-level vs container-level spacing")
+- [ ] Renders correctly with no theme file loaded
+
+### Theme
+
+- [ ] Tokens added to `tokens.base.scss` if needed
+- [ ] Dark mode overrides added to `tokens.dark.scss` if component has color tokens
+- [ ] Verified in both light and dark modes
+
+### Tests
+
+- [ ] `should create` test
+- [ ] Default input values tested
+- [ ] Host class presence tested
+- [ ] Variant classes tested
+- [ ] Content projection tested if applicable
+- [ ] Base props passthrough tested
+- [ ] All tests pass
+
+### Storybook
+
+- [ ] Default story
+- [ ] Story for each variant
+- [ ] Story for each size if applicable
+- [ ] Disabled story if applicable
+- [ ] Loading story if applicable
+- [ ] `AllVariants` composite story
+- [ ] Stories render correctly in Storybook with fallback defaults
+
+### Documentation
+
+- [ ] README follows the exact section order defined in this guide
+- [ ] API table is complete with all inputs, outputs, and content slots
+- [ ] Design tokens documented with override examples
+- [ ] Accessibility behavior documented
+- [ ] Import path uses `@frame-kit/ui-ng`
+
+### Public API
+
+- [ ] Component, types, and any associated directives exported from the component's entry-point `index.ts` (or the forms sub-barrel for `forms` components)
+- [ ] New entry point re-exported from the primary `packages/ui-ng/index.ts` (skip for `forms` — already aggregated)
+- [ ] `nx build ui-ng` succeeds and emits the new entry point's FESM + `exports` map entry