@frame-kit/ui-ng 0.0.1

package/ui/button/README.md

@@ -0,0 +1,184 @@
+# fk-button
+
+A token-driven button component for Angular that supports visual variants, sizes, loading state, icons, and accessible interaction patterns.
+
+---
+
+## API
+
+### Inputs
+
+| Input             | Type             | Default     | Description                                                              |
+| ----------------- | ---------------- | ----------- | ------------------------------------------------------------------------ |
+| `variant`         | `ButtonVariant`  | `"primary"` | Visual style of the button (for example `primary`, `secondary`, `ghost`) |
+| `size`            | `ButtonSize`     | `"md"`      | Size of the button (`sm`, `md`, `lg`)                                    |
+| `loading`         | `boolean`        | `false`     | Shows a loader and disables interaction                                  |
+| `disabled`        | `boolean`        | `false`     | Disables the button                                                      |
+| `fullWidth`       | `boolean`        | `false`     | Stretches the button host to fill its parent's inline size               |
+| `type`            | `ButtonType`     | `"button"`  | Native button type (`"button"`, `"submit"`, `"reset"`)                   |
+| `id`              | `string \| null` | `null`      | Optional ID for the button element                                       |
+| `className`       | `string`         | `''`        | Additional CSS classes merged onto the host element                      |
+| `ariaLabel`       | `string \| null` | `null`      | ARIA label for icon-only or ambiguous buttons                            |
+| `ariaDescribedBy` | `string \| null` | `null`      | IDs of additional descriptive elements                                   |
+
+The button label and icons are provided via content projection:
+
+```html
+<fk-button>Save</fk-button>
+```
+
+### Icon directives
+
+Icons are projected into the button using structural directives rather than inputs. Import `FkButtonIconStartDirective` and/or `FkButtonIconEndDirective` alongside `IconComponent`:
+
+| Directive           | Selector              | Description                              |
+| ------------------- | --------------------- | ---------------------------------------- |
+| `fkButtonIconStart` | `[fkButtonIconStart]` | Projects an icon before the button label |
+| `fkButtonIconEnd`   | `[fkButtonIconEnd]`   | Projects an icon after the button label  |
+
+Both directives apply `aria-hidden="true"` automatically.
+
+### Outputs
+
+`fk-button` relies on the native `click` event and does not expose custom Angular outputs. Listen via `(click)`:
+
+```html
+<fk-button (click)="onSave()">Save</fk-button>
+```
+
+---
+
+## Features
+
+- Multiple visual variants and sizes
+- Loading state with spinner integration
+- Icon support via `fkButtonIconStart` and `fkButtonIconEnd` content projection directives
+- Disabled and loading states prevent interaction
+- Token-driven styling for color, radius, spacing, and typography
+
+---
+
+## Quick Start
+
+```html
+<fk-button variant="primary" (click)="onSave()"> Save changes </fk-button>
+```
+
+---
+
+## Import
+
+```ts
+import { ButtonComponent, FkButtonIconStartDirective, FkButtonIconEndDirective, IconComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [ButtonComponent, FkButtonIconStartDirective, FkButtonIconEndDirective, IconComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-button></fk-button>
+```
+
+---
+
+## Examples
+
+### Variants
+
+```html
+<fk-button variant="primary">Primary</fk-button>
+<fk-button variant="secondary">Secondary</fk-button>
+<fk-button variant="ghost">Ghost</fk-button>
+```
+
+### Sizes
+
+```html
+<fk-button size="sm">Small</fk-button>
+<fk-button size="md">Medium</fk-button>
+<fk-button size="lg">Large</fk-button>
+```
+
+### With icon (start)
+
+```html
+<fk-button variant="primary">
+  <fk-icon fkButtonIconStart name="plus" size="sm"></fk-icon>
+  New record
+</fk-button>
+```
+
+### With icon (end)
+
+```html
+<fk-button variant="secondary">
+  Next step
+  <fk-icon fkButtonIconEnd name="arrow-right" size="sm"></fk-icon>
+</fk-button>
+```
+
+### Loading state
+
+```html
+<fk-button variant="primary" [loading]="isSaving" (click)="save()"> Save changes </fk-button>
+```
+
+---
+
+## Accessibility
+
+- Renders a native `<button>` element with proper keyboard interaction.
+- Uses `aria-disabled="true"` when `loading` or `disabled` to signal non-interactive state.
+- For icon-only buttons, always provide an `ariaLabel`:
+
+```html
+<fk-button ariaLabel="Delete record">
+  <fk-icon fkButtonIconStart name="trash" size="sm"></fk-icon>
+</fk-button>
+```
+
+---
+
+## Design Tokens
+
+`fk-button` is styled entirely through design tokens, typically including:
+
+```scss
+--fk-button-radius;
+--fk-button-font-weight;
+--fk-button-padding-inline;
+--fk-button-gap;
+
+--fk-button-primary-bg;
+--fk-button-primary-color;
+--fk-button-primary-border-color;
+
+--fk-button-secondary-bg;
+--fk-button-secondary-color;
+--fk-button-secondary-border-color;
+```
+
+Override tokens in your stylesheet:
+
+```scss
+:root {
+  --fk-button-radius: 9999px;
+}
+```
+
+---
+
+## Behavior Notes
+
+- `loading` implies a disabled state for interaction, but you still control `disabled` independently.
+- `type` defaults to `"button"` to avoid accidental form submissions inside `<form>` elements.

package/ui/callout/README.md

@@ -0,0 +1,159 @@
+# fk-callout
+
+A token-driven callout component for highlighting supplementary information such as tips, notices, or contextual messages.
+
+---
+
+## API
+
+### Inputs
+
+| Input             | Type                  | Default   | Description                                  |
+| ----------------- | --------------------- | --------- | -------------------------------------------- |
+| `title`           | `string \| null`      | `null`    | Optional headline rendered via `fk-headline` |
+| `align`           | `'start' \| 'center'` | `'start'` | Text alignment of the description            |
+| `backgroundColor` | `string \| null`      | `null`    | Custom background color (overrides token)    |
+| `borderColor`     | `string \| null`      | `null`    | Custom border color (overrides token)        |
+| `className`       | `string`              | `''`      | Additional CSS classes for the host element  |
+
+### Content projection
+
+The callout body is the projected content (default `<ng-content />`). Pass plain text or template fragments — the component never renders untrusted HTML through `[innerHTML]`.
+
+### Outputs
+
+`fk-callout` is presentational and does not emit outputs.
+
+---
+
+## Features
+
+- Optional title with a projected description body
+- Text alignment control
+- Custom background and border colors via inputs
+- Token-driven styling
+- Description accepts arbitrary template content via projection (no `innerHTML`)
+
+---
+
+## Quick Start
+
+```html
+<fk-callout title="Heads up">Your session will expire in 5 minutes.</fk-callout>
+```
+
+---
+
+## Import
+
+```ts
+import { CalloutComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [CalloutComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-callout></fk-callout>
+```
+
+---
+
+## Examples
+
+### Title and description
+
+```html
+<fk-callout title="Important">Please review the details before submitting.</fk-callout>
+```
+
+### Description only
+
+```html
+<fk-callout>A verification email has been sent to your inbox.</fk-callout>
+```
+
+### Title only
+
+```html
+<fk-callout title="No new notifications" />
+```
+
+### Centered text
+
+```html
+<fk-callout title="Welcome" align="center">Your account has been created.</fk-callout>
+```
+
+### Rich content via projection
+
+```html
+<fk-callout title="Idempotency"> Send an <code>Idempotency-Key</code> header to make retries safe. </fk-callout>
+```
+
+### Custom colors
+
+```html
+<fk-callout title="Info" backgroundColor="#f0f9ff" borderColor="#0ea5e9"> This uses custom colors. </fk-callout>
+```
+
+---
+
+## Accessibility
+
+- The title renders as an `fk-headline` (`h6`), providing a semantic heading for assistive technologies.
+- Body content is projected as live template nodes, so links and interactive children participate in the normal accessibility tree.
+- The component is presentational; wrap it in a landmark or live region if it conveys time-sensitive information.
+
+---
+
+## Design Tokens
+
+`fk-callout` is styled entirely through design tokens.
+
+```scss
+--fk-callout-bg
+--fk-callout-border-color
+--fk-callout-padding
+--fk-callout-border-radius
+--fk-callout-font-size
+--fk-callout-title-font-size
+--fk-callout-title-gap
+```
+
+Override tokens in your theme stylesheet:
+
+```scss
+:root {
+  --fk-callout-bg: #fffbeb;
+  --fk-callout-border-color: #f59e0b;
+  --fk-callout-padding: 1.5rem;
+}
+```
+
+Or scope overrides to a specific context:
+
+```scss
+.dark-theme fk-callout {
+  --fk-callout-bg: #1e1e2e;
+  --fk-callout-border-color: #334155;
+}
+```
+
+---
+
+## Behavior Notes
+
+- `backgroundColor` and `borderColor` inputs override the corresponding token values via `@HostBinding` inline styles.
+- When `title` is `null` and no content is projected, the component renders an empty container — avoid this in practice.
+- The body is projected (`<ng-content />`) — there is no `[innerHTML]` sink, so no caller can inject HTML strings through the API.

package/ui/card/README.md

@@ -0,0 +1,174 @@
+# fk-card
+
+A token-driven container component for grouping related content with consistent padding, background, border, and alignment.
+
+---
+
+## API
+
+### Inputs
+
+| Input       | Type                                        | Default     | Description                                                    |
+| ----------- | ------------------------------------------- | ----------- | -------------------------------------------------------------- |
+| `size`      | `'sm' \| 'md' \| 'lg' \| string`            | `'md'`      | Padding preset or custom CSS value (e.g. `'3rem'`)             |
+| `align`     | `'start' \| 'center' \| 'end' \| 'stretch'` | `'stretch'` | Cross-axis alignment of projected content                      |
+| `className` | `string`                                    | `''`        | Additional CSS classes for the host element                    |
+| `id`        | `string \| null`                            | `null`      | Sets the `id` attribute on the host element                    |
+| `ariaLabel` | `string \| null`                            | `null`      | Sets `aria-label` on the host element for assistive technology |
+
+### Outputs
+
+`fk-card` is presentational and does not emit outputs.
+
+### Content
+
+Card content is provided through content projection.
+
+```html
+<fk-card>
+  <h2>Title</h2>
+  <p>Card body content goes here.</p>
+</fk-card>
+```
+
+---
+
+## Features
+
+- Preset and custom padding sizes
+- Cross-axis content alignment
+- Token-driven styling
+- Self-sufficient rendering without any theme file loaded
+
+---
+
+## Quick Start
+
+```html
+<fk-card size="md">
+  <p>Hello from inside a card.</p>
+</fk-card>
+```
+
+---
+
+## Import
+
+```ts
+import { CardComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [CardComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-card></fk-card>
+```
+
+---
+
+## Examples
+
+### Small
+
+```html
+<fk-card size="sm">
+  <p>Compact content area.</p>
+</fk-card>
+```
+
+### Medium (default)
+
+```html
+<fk-card>
+  <p>Standard content area.</p>
+</fk-card>
+```
+
+### Large
+
+```html
+<fk-card size="lg">
+  <p>Spacious content area.</p>
+</fk-card>
+```
+
+### Custom padding
+
+```html
+<fk-card size="3rem">
+  <p>Custom padding applied directly.</p>
+</fk-card>
+```
+
+### Centered content
+
+```html
+<fk-card align="center">
+  <fk-icon-badge name="check" />
+  <fk-headline [level]="3">Success</fk-headline>
+  <p>Your changes have been saved.</p>
+</fk-card>
+```
+
+---
+
+## Accessibility
+
+- `fk-card` is a presentational container and does not imply a landmark role.
+- Use `ariaLabel` when the card represents a distinct, labeled region.
+- For interactive cards, wrap the content in an appropriate interactive element rather than making the card itself clickable.
+
+---
+
+## Design Tokens
+
+`fk-card` is styled entirely through design tokens.
+
+```
+--fk-card-bg
+--fk-card-border-color
+--fk-card-border-radius
+--fk-card-padding-sm
+--fk-card-padding-md
+--fk-card-padding-lg
+```
+
+### Customizing Tokens
+
+Override tokens in your application's global stylesheet or a scoped selector:
+
+```scss
+:root {
+  --fk-card-bg: #fafafa;
+  --fk-card-border-color: #e5e7eb;
+  --fk-card-border-radius: 1rem;
+}
+```
+
+Or scope overrides to a specific context:
+
+```scss
+.dark-theme fk-card {
+  --fk-card-bg: #1e1e2e;
+  --fk-card-border-color: #334155;
+}
+```
+
+---
+
+## Behavior Notes
+
+- When `size` is a preset (`sm`, `md`, `lg`), padding is controlled via the corresponding token. When `size` is a custom string, it is applied directly as inline `padding`.
+- The card renders as a flex column container, so projected content flows vertically by default.
+- `align` controls `align-items` on the flex container, affecting horizontal alignment of children.