@frame-kit/ui-ng 0.0.1

package/core/image/README.md

@@ -0,0 +1,210 @@
+# fk-image
+
+A flexible image component for Angular with support for fill mode, aspect ratio, fallbacks, and token-driven styling.
+
+---
+
+## API
+
+### Required inputs
+
+| Input | Type     | Description                 |
+| ----- | -------- | --------------------------- |
+| `src` | `string` | Image source URL            |
+| `alt` | `string` | Accessible alternative text |
+
+### Dimension & layout
+
+| Input         | Type                       | Default | Description                                                 |
+| ------------- | -------------------------- | ------- | ----------------------------------------------------------- |
+| `fill`        | `boolean`                  | `false` | Makes the image fill its container via absolute positioning |
+| `width`       | `number \| null`           | `null`  | Explicit width (required when `fill` is `false`)            |
+| `height`      | `number \| null`           | `null`  | Explicit height (required when `fill` is `false`)           |
+| `aspectRatio` | `number \| string \| null` | `null`  | Optional aspect ratio (e.g. `16 / 9` or `"16 / 9"`)         |
+
+In dev mode, `fk-image` will warn if `fill` is `false` and neither `width` nor `height` is provided, to help avoid layout shift.
+
+### Image behavior
+
+| Input            | Type                       | Default   | Description                                      |
+| ---------------- | -------------------------- | --------- | ------------------------------------------------ |
+| `srcSet`         | `string \| null`           | `null`    | Native `srcset` attribute for responsive images  |
+| `sizes`          | `string \| null`           | `null`    | Native `sizes` attribute for responsive images   |
+| `loading`        | `ImageLoading`             | `"lazy"`  | Native `loading` attribute (`"lazy" \| "eager"`) |
+| `decoding`       | `ImageDecoding`            | `"async"` | Native `decoding` attribute                      |
+| `fetchPriority`  | `ImageFetchPriority`       | `"auto"`  | Native `fetchpriority` attribute                 |
+| `crossOrigin`    | `ImageCrossOrigin \| null` | `null`    | Native `crossorigin` attribute                   |
+| `referrerPolicy` | `string \| null`           | `null`    | Native `referrerpolicy` attribute                |
+
+### Presentation
+
+| Input      | Type          | Default    | Description             |
+| ---------- | ------------- | ---------- | ----------------------- |
+| `fit`      | `ImageFit`    | `"cover"`  | `object-fit` behavior   |
+| `position` | `string`      | `"center"` | `object-position` value |
+| `radius`   | `ImageRadius` | `"none"`   | Corner radius variant   |
+
+### Fallback
+
+| Input         | Type             | Default | Description                                               |
+| ------------- | ---------------- | ------- | --------------------------------------------------------- |
+| `fallbackSrc` | `string \| null` | `null`  | Optional fallback image source if the primary `src` fails |
+
+### Base props
+
+| Input       | Type             | Default | Description                                 |
+| ----------- | ---------------- | ------- | ------------------------------------------- |
+| `className` | `string`         | `''`    | Additional CSS classes merged onto the host |
+| `id`        | `string \| null` | `null`  | Optional ID for the wrapper element         |
+
+### Outputs
+
+| Output       | Type   | Description                               |
+| ------------ | ------ | ----------------------------------------- |
+| `imageLoad`  | `void` | Emitted when the image successfully loads |
+| `imageError` | `void` | Emitted when the image fails to load      |
+
+---
+
+## Features
+
+- Required `alt` text for accessibility
+- Fill mode (`fill=true`) for background-like behavior
+- Optional width/height with dev-time warning to prevent layout shift
+- Fallback image support via `fallbackSrc`
+- Responsive images via `srcset` / `sizes`
+- Aspect ratio and corner radius tokens
+
+---
+
+## Quick Start
+
+\`\`\`html
+<fk-image
+src="/assets/property-1.jpg"
+alt="Front view of a two-story house"
+[width]="400"
+[height]="300"
+fit="cover"
+/>
+\`\`\`
+
+---
+
+## Import
+
+\`\`\`ts
+import { ImageComponent } from "@frame-kit/ui-ng";
+\`\`\`
+
+\`\`\`ts
+@Component({
+selector: "app-example",
+imports: [ImageComponent],
+templateUrl: "./example.component.html",
+})
+export class ExampleComponent {}
+\`\`\`
+
+---
+
+## Selector
+
+\`\`\`html
+<fk-image></fk-image>
+\`\`\`
+
+---
+
+## Examples
+
+### Responsive card image
+
+\`\`\`html
+
+<div class="property-card">
+  <fk-image
+    src="/assets/property-1.jpg"
+    alt="Modern condo in downtown"
+    [width]="480"
+    [height]="320"
+    fit="cover"
+    radius="md"
+  />
+</div>
+\`\`\`
+
+### Fill mode hero image
+
+\`\`\`html
+
+<div class="hero-image-wrapper">
+  <fk-image
+    src="/assets/city-skyline.jpg"
+    alt="City skyline at sunset"
+    [fill]="true"
+    fit="cover"
+    position="center"
+  />
+</div>
+\`\`\`
+
+\`\`\`scss
+.hero-image-wrapper {
+position: relative;
+width: 100%;
+height: 320px;
+}
+\`\`\`
+
+### With fallback
+
+\`\`\`html
+<fk-image
+src="https://example.com/main-image.jpg"
+fallbackSrc="/assets/fallback.jpg"
+alt="Agent headshot"
+[width]="128"
+[height]="128"
+radius="full"
+/>
+\`\`\`
+
+---
+
+## Accessibility
+
+- Always requires `alt` text; use descriptive language for important content
+- Use `alt=""` only for decorative images where the surrounding context is enough
+- Emits `imageError` so you can log or recover when the image fails
+
+---
+
+## Design Tokens
+
+`fk-image` relies on shared image/shape tokens:
+
+\`\`\`scss
+--fk-image-radius-none;
+--fk-image-radius-sm;
+--fk-image-radius-md;
+--fk-image-radius-lg;
+--fk-image-radius-full;
+\`\`\`
+
+You can also rely on global layout tokens for spacing around the image.
+
+Override tokens in your stylesheet:
+
+\`\`\`scss
+:root {
+--fk-image-radius-md: 0.75rem;
+}
+\`\`\`
+
+---
+
+## Behavior Notes
+
+- When `fallbackSrc` is set, a failed load will automatically switch to the fallback once
+- Dev-mode logs a warning when neither `fill` nor explicit `width`/`height` is provided, to help you avoid CLS issues

package/core/link/README.md

@@ -0,0 +1,297 @@
+# Link Component
+
+A flexible, accessible link component for the FrameKit UI library.
+
+## Features
+
+- ✅ **Angular Router Integration** — Seamless routing with `routerLink`
+- ✅ **External Link Support** — Automatic detection, icons, and security (`target="_blank"`, `rel="noopener noreferrer"`)
+- ✅ **Design Token System** — CSS custom properties for theming
+- ✅ **Variants** — Default, primary, muted, danger
+- ✅ **Sizes** — Small, medium, large
+- ✅ **Underline Styles** — None, hover (default), always
+- ✅ **Accessibility** — ARIA labels, keyboard navigation, screen reader support
+- ✅ **Analytics Tracking** — Data attributes for tracking (trackingId, trackingCategory, trackingLabel)
+- ✅ **States** — Disabled, loading
+- ✅ **Download Links** — Support for file downloads
+- ✅ **Custom Data Attributes** — Flexible metadata support
+
+## Quick Start
+
+```html
+<fk-link href="https://example.com">Visit Example</fk-link>
+```
+
+```html
+<fk-link routerLink="/dashboard" variant="primary">Open dashboard</fk-link>
+```
+
+## Import
+
+```ts
+import { LinkComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [LinkComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+## Usage
+
+### Basic Link
+
+```html
+<fk-link href="https://example.com">Visit Example</fk-link>
+```
+
+### Internal Navigation (Angular Router)
+
+```html
+<fk-link routerLink="/dashboard">Go to Dashboard</fk-link>
+```
+
+### External Link with Icon
+
+```html
+<fk-link href="https://example.com" [external]="true"> External Site </fk-link>
+```
+
+### Variants
+
+```html
+<fk-link href="#" variant="default">Default Link</fk-link>
+<fk-link href="#" variant="primary">Primary Link</fk-link>
+<fk-link href="#" variant="muted">Muted Link</fk-link>
+<fk-link href="#" variant="danger">Delete Account</fk-link>
+```
+
+### Sizes
+
+```html
+<fk-link href="#" size="small">Small Link</fk-link>
+<fk-link href="#" size="medium">Medium Link</fk-link>
+<fk-link href="#" size="large">Large Link</fk-link>
+```
+
+### Underline Styles
+
+```html
+<fk-link href="#" underline="none">No Underline</fk-link>
+<fk-link href="#" underline="hover">Hover Underline</fk-link>
+<fk-link href="#" underline="always">Always Underlined</fk-link>
+```
+
+### Disabled State
+
+```html
+<fk-link href="#" [disabled]="true">Disabled Link</fk-link>
+```
+
+### Loading State
+
+```html
+<fk-link href="#" [loading]="isLoading">Loading...</fk-link>
+```
+
+### Analytics Tracking
+
+```html
+<fk-link href="/products" trackingId="nav-products" trackingCategory="navigation" trackingLabel="header-menu"> Products </fk-link>
+```
+
+### Custom Data Attributes
+
+```html
+<fk-link href="/signup" [dataAttributes]="{ 'data-test-id': 'signup-cta', 'data-priority': 'high' }"> Sign Up </fk-link>
+```
+
+### Download Link
+
+```html
+<fk-link href="/files/report.pdf" [download]="'monthly-report.pdf'"> Download Report </fk-link>
+```
+
+### Accessibility
+
+```html
+<fk-link href="/settings" ariaLabel="Go to account settings page" ariaCurrent="page"> Settings </fk-link>
+```
+
+## API
+
+### Inputs
+
+| Input              | Type                                                                              | Default     | Description                                                |
+| ------------------ | --------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------- |
+| `href`             | `string \| null`                                                                  | `null`      | External href (for standard `<a>` tags)                    |
+| `routerLink`       | `string \| string[] \| null`                                                      | `null`      | Angular Router link (for internal navigation)              |
+| `variant`          | `'default' \| 'primary' \| 'muted' \| 'danger'`                                   | `'default'` | Visual variant                                             |
+| `size`             | `'small' \| 'medium' \| 'large'`                                                  | `'medium'`  | Link size                                                  |
+| `underline`        | `'none' \| 'hover' \| 'always'`                                                   | `'hover'`   | Underline behavior                                         |
+| `target`           | `string \| null`                                                                  | `null`      | Target attribute (auto `_blank` for external)              |
+| `rel`              | `string \| null`                                                                  | `null`      | Rel attribute (auto `noopener noreferrer` for external)    |
+| `external`         | `boolean`                                                                         | `false`     | Mark as external link (shows icon, sets `target="_blank"`) |
+| `disabled`         | `boolean`                                                                         | `false`     | Disable the link                                           |
+| `loading`          | `boolean`                                                                         | `false`     | Show loading state                                         |
+| `download`         | `string \| boolean \| null`                                                       | `null`      | Download attribute (for file downloads)                    |
+| `className`        | `string`                                                                          | `''`        | Additional CSS classes                                     |
+| `id`               | `string \| null`                                                                  | `null`      | ID attribute                                               |
+| `ariaLabel`        | `string \| null`                                                                  | `null`      | ARIA label                                                 |
+| `ariaDescribedBy`  | `string \| null`                                                                  | `null`      | ARIA described-by                                          |
+| `ariaCurrent`      | `'page' \| 'step' \| 'location' \| 'date' \| 'time' \| 'true' \| 'false' \| null` | `null`      | ARIA current (for indicating current page/location)        |
+| `role`             | `string \| null`                                                                  | `null`      | Role attribute                                             |
+| `tabIndex`         | `number \| null`                                                                  | `null`      | Tab index (auto `-1` when disabled)                        |
+| `trackingId`       | `string \| null`                                                                  | `null`      | Analytics tracking ID                                      |
+| `trackingCategory` | `string \| null`                                                                  | `null`      | Analytics tracking category                                |
+| `trackingLabel`    | `string \| null`                                                                  | `null`      | Analytics tracking label                                   |
+| `dataAttributes`   | `Record<string, string>`                                                          | `{}`        | Custom data attributes                                     |
+
+### Outputs
+
+| Output    | Type                       | Description                                                       |
+| --------- | -------------------------- | ----------------------------------------------------------------- |
+| `clicked` | `EventEmitter<MouseEvent>` | Emitted when link is clicked (not emitted if disabled or loading) |
+
+## Design Tokens
+
+The Link component uses CSS custom properties for theming:
+
+All tokens are defined in `theme/tokens.base.scss`. See `theme/TOKENS.md` for the full contract.
+
+```scss
+// Key link tokens (all --fk-* namespaced):
+--fk-link-color-default
+--fk-link-color-default-hover
+--fk-link-color-primary
+--fk-link-color-primary-hover
+--fk-link-color-primary-active
+--fk-link-color-muted
+--fk-link-color-muted-hover
+--fk-link-color-danger
+--fk-link-color-danger-hover
+--fk-link-color-disabled
+--fk-link-font-size-small
+--fk-link-font-size-medium
+--fk-link-font-size-large
+```
+
+## Accessibility Features
+
+- ✅ **Semantic HTML** — Uses `<a>` for links, `<button>` for button-style links
+- ✅ **Keyboard Navigation** — Full keyboard support (Enter, Space for buttons)
+- ✅ **Focus Indicators** — Visible focus ring (respects `:focus-visible`)
+- ✅ **ARIA Attributes** — Support for `aria-label`, `aria-describedby`, `aria-current`
+- ✅ **Disabled State** — Sets `tabindex="-1"` and prevents navigation
+- ✅ **External Link Indication** — Visual icon (hidden from screen readers with `aria-hidden="true"`)
+- ✅ **Loading State** — Prevents navigation and shows visual feedback
+
+## Best Practices
+
+### When to Use routerLink vs href
+
+```html
+<!-- Use routerLink for internal app navigation -->
+<fk-link routerLink="/dashboard">Dashboard</fk-link>
+
+<!-- Use href for external links -->
+<fk-link href="https://example.com" [external]="true">External</fk-link>
+
+<!-- Use href for anchor links -->
+<fk-link href="#section">Jump to Section</fk-link>
+```
+
+### External Links
+
+Always mark external links explicitly or let the component auto-detect:
+
+```html
+<!-- Auto-detection (recommended) -->
+<fk-link href="https://example.com">External</fk-link>
+
+<!-- Explicit (for internal URLs that should open in new tab) -->
+<fk-link href="/internal" [external]="true">New Tab</fk-link>
+```
+
+### Accessibility
+
+```html
+<!-- Provide aria-label for icon-only links -->
+<fk-link href="https://github.com" ariaLabel="Visit our GitHub repository">
+  <svg>...</svg>
+</fk-link>
+
+<!-- Use aria-current for current page -->
+<fk-link routerLink="/home" ariaCurrent="page">Home</fk-link>
+```
+
+### Analytics Tracking
+
+```html
+<!-- Structured tracking data -->
+<fk-link href="/signup" trackingId="cta-signup-header" trackingCategory="cta" trackingLabel="header"> Sign Up </fk-link>
+```
+
+## Examples
+
+### Navigation Menu
+
+```html
+<nav>
+  <fk-link routerLink="/" ariaCurrent="page" underline="none">Home</fk-link>
+  <fk-link routerLink="/products" underline="none">Products</fk-link>
+  <fk-link routerLink="/pricing" underline="none">Pricing</fk-link>
+  <fk-link href="https://blog.example.com" [external]="true" underline="none"> Blog </fk-link>
+</nav>
+```
+
+### Footer Links
+
+```html
+<footer>
+  <div>
+    <h4>Company</h4>
+    <fk-link routerLink="/about" variant="muted" size="small">About</fk-link>
+    <fk-link routerLink="/careers" variant="muted" size="small">Careers</fk-link>
+    <fk-link href="https://blog.example.com" [external]="true" variant="muted" size="small"> Blog </fk-link>
+  </div>
+</footer>
+```
+
+### Call-to-Action
+
+```html
+<fk-link href="/signup" variant="primary" size="large" underline="none"> Get Started Free → </fk-link>
+```
+
+## Testing
+
+The component includes comprehensive unit tests covering:
+
+- External link detection
+- Target and rel attributes
+- Tab index behavior
+- Click handling (disabled, loading states)
+- Analytics data attributes
+- CSS class merging
+- All variants, sizes, and underline styles
+
+Run tests:
+
+```bash
+npm run test:ui
+```
+
+## Storybook
+
+View all component variations in Storybook:
+
+```bash
+npm run storybook
+```
+
+Navigate to **Atoms → Link** to see interactive examples.

package/core/separator/README.md

@@ -0,0 +1,145 @@
+# fk-separator
+
+A horizontal rule component for visually dividing content sections, styled entirely through design tokens.
+
+---
+
+## API
+
+### Inputs
+
+| Input          | Type             | Default | Description                                                |
+| -------------- | ---------------- | ------- | ---------------------------------------------------------- |
+| `marginTop`    | `string \| null` | `null`  | Custom top margin (sets `--fk-separator-margin-top`)       |
+| `marginBottom` | `string \| null` | `null`  | Custom bottom margin (sets `--fk-separator-margin-bottom`) |
+| `color`        | `string \| null` | `null`  | Custom line color (sets `--fk-separator-color`)            |
+| `className`    | `string`         | `''`    | Additional CSS classes merged onto the host element        |
+
+### Outputs
+
+None.
+
+---
+
+## Features
+
+- Token-driven styling for color and spacing
+- Per-instance overrides via inputs
+- Renders a semantic `<hr>` element
+- `role="separator"` on the host for accessibility
+- Self-sufficient rendering without any theme file loaded
+
+---
+
+## Quick Start
+
+```html
+<fk-separator />
+```
+
+---
+
+## Import
+
+```ts
+import { SeparatorComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [SeparatorComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-separator></fk-separator>
+```
+
+---
+
+## Examples
+
+### Default separator
+
+```html
+<fk-separator />
+```
+
+### Custom spacing
+
+```html
+<fk-separator marginTop="2rem" marginBottom="1rem" />
+```
+
+### Custom color
+
+```html
+<fk-separator color="#e02424" />
+```
+
+---
+
+## Accessibility
+
+`fk-separator` renders a native `<hr>` element with `role="separator"` on the host.
+
+Accessibility behavior:
+
+- Semantic separator role for screen readers
+- Visual divider between content sections
+
+---
+
+## Design Tokens
+
+`fk-separator` is styled entirely through design tokens.
+
+### Component-specific tokens
+
+```
+--fk-separator-color
+--fk-separator-margin-top
+--fk-separator-margin-bottom
+--fk-separator-border-width
+```
+
+### Shared tokens
+
+```
+--fk-color-border
+--fk-rhythm-6
+```
+
+### Customizing Tokens
+
+Override tokens in your application's stylesheet:
+
+```scss
+:root {
+  --fk-separator-color: #e5e7eb;
+  --fk-separator-margin-top: 2rem;
+  --fk-separator-margin-bottom: 1rem;
+}
+```
+
+Or scope overrides to a specific context:
+
+```scss
+.compact-layout fk-separator {
+  --fk-separator-margin-top: 0.5rem;
+}
+```
+
+---
+
+## Behavior Notes
+
+- Default margin is applied via `--fk-separator-margin-top` (top only); bottom margin defaults to `0`
+- Per-instance `marginTop`, `marginBottom`, and `color` inputs override the corresponding tokens inline