@kouji-ui/components 0.1.1

package/src/avatar/avatar-group.spec.ts

@@ -0,0 +1,138 @@
+import { Component } from '@angular/core';
+import { render } from '@testing-library/angular';
+
+import { KjAvatarComponent } from './avatar';
+import { KjAvatarGroupComponent } from './avatar-group';
+
+const imports = [KjAvatarComponent, KjAvatarGroupComponent];
+
+/**
+ * Allow Angular's signal-driven `effect()`s and `contentChildren` queries to
+ * settle before the assertions read host attributes. Mirrors the helper used
+ * by the core `KjAvatarGroup` spec.
+ */
+async function flush(): Promise<void> {
+  await new Promise<void>((resolve) => setTimeout(resolve, 0));
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+describe('KjAvatarGroupComponent', () => {
+  it('renders projected <kj-avatar> children', async () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `
+        <kj-avatar-group>
+          <kj-avatar content="A" />
+          <kj-avatar content="B" />
+          <kj-avatar content="C" />
+        </kj-avatar-group>`,
+    })
+    class Host {}
+
+    const { container } = await render(Host);
+    await flush();
+
+    const groupEl = container.querySelector('kj-avatar-group') as HTMLElement;
+    expect(groupEl).toBeTruthy();
+    // The class binding mirrors the wrapper's host class.
+    expect(groupEl.classList.contains('kj-avatar-group')).toBe(true);
+
+    // Three projected avatars + (potentially) the chip. With default kjMax=4
+    // and three children, the chip should NOT render.
+    expect(groupEl.querySelectorAll('kj-avatar')).toHaveLength(3);
+    expect(groupEl.querySelector('.kj-avatar-group-overflow')).toBeNull();
+  });
+
+  it('renders the overflow chip with "+N" when children exceed kjMax', async () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `
+        <kj-avatar-group [kjMax]="2">
+          <kj-avatar content="A" />
+          <kj-avatar content="B" />
+          <kj-avatar content="C" />
+          <kj-avatar content="D" />
+          <kj-avatar content="E" />
+        </kj-avatar-group>`,
+    })
+    class Host {}
+
+    const { container } = await render(Host);
+    await flush();
+
+    const chip = container.querySelector('.kj-avatar-group-overflow') as HTMLElement;
+    expect(chip).toBeTruthy();
+    // 5 projected children, kjMax=2 → overflow = 3.
+    expect(chip.textContent?.trim()).toBe('+3');
+  });
+
+  it('overflow chip is aria-hidden so it does not duplicate the count-aware label', async () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `
+        <kj-avatar-group [kjMax]="1">
+          <kj-avatar content="A" />
+          <kj-avatar content="B" />
+          <kj-avatar content="C" />
+        </kj-avatar-group>`,
+    })
+    class Host {}
+
+    const { container } = await render(Host);
+    await flush();
+
+    const chip = container.querySelector('.kj-avatar-group-overflow') as HTMLElement;
+    expect(chip).toBeTruthy();
+    expect(chip.getAttribute('aria-hidden')).toBe('true');
+  });
+
+  it('forwards aliased inputs (kjMax, kjAriaLabel, kjTotal) to the underlying directive', async () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `
+        <kj-avatar-group [kjMax]="3" kjAriaLabel="collaborators" [kjTotal]="42">
+          <kj-avatar content="A" />
+          <kj-avatar content="B" />
+          <kj-avatar content="C" />
+        </kj-avatar-group>`,
+    })
+    class Host {}
+
+    const { container } = await render(Host);
+    await flush();
+
+    const groupEl = container.querySelector('kj-avatar-group') as HTMLElement;
+    // Count-aware label proves kjAriaLabel + kjTotal reached the directive.
+    expect(groupEl.getAttribute('aria-label')).toBe('3 of 42 collaborators');
+    expect(groupEl.getAttribute('role')).toBe('group');
+
+    // Chip with kjMax=3 and 3 projected (and kjTotal=42) → overflow = 39.
+    const chip = container.querySelector('.kj-avatar-group-overflow') as HTMLElement;
+    expect(chip).toBeTruthy();
+    expect(chip.textContent?.trim()).toBe('+39');
+  });
+
+  it('renders nothing problematic when the group is empty', async () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `<kj-avatar-group [kjMax]="3"></kj-avatar-group>`,
+    })
+    class Host {}
+
+    const { container } = await render(Host);
+    await flush();
+
+    const groupEl = container.querySelector('kj-avatar-group') as HTMLElement;
+    expect(groupEl).toBeTruthy();
+    // No chip when there is nothing to overflow.
+    expect(container.querySelector('.kj-avatar-group-overflow')).toBeNull();
+    // Empty group omits aria-label entirely (count-aware label suppressed at total === 0).
+    expect(groupEl.hasAttribute('aria-label')).toBe(false);
+  });
+});

package/src/avatar/avatar-group.ts

@@ -0,0 +1,127 @@
+import { ChangeDetectionStrategy, Component, ViewEncapsulation, computed, inject } from '@angular/core';
+import { KjAvatarGroup, KJ_AVATAR_GROUP, type KjAvatarGroupAriaLabelFormat, type KjAvatarShape } from '@kouji-ui/core';
+import { KjAvatarComponent } from './avatar';
+
+/**
+ * Avatar group wrapper. Stacks projected `<kj-avatar>` children with a
+ * count-aware `aria-label`, an overflow chip when `kjMax` is exceeded, and
+ * RTL-aware z-index ordering — all handled by the composed `KjAvatarGroup`
+ * core directive. The wrapper supplies the chip element and the host
+ * `<ng-content/>` slot.
+ *
+ * The overflow chip is a regular `<kj-avatar>` rendering `'+N'` text; it is
+ * `aria-hidden` because the group's count-aware label already conveys
+ * totality (e.g. `"3 of 8 collaborators"`), so exposing the chip again would
+ * duplicate the announcement.
+ *
+ * @doc-example Default
+ *   The default playground — five stacked avatars with the group's defaults.
+ *   @doc-file avatar-group.example.ts
+ * @doc-example Usage
+ *   The common shape: a small face-pile with an overflow chip, accessible label,
+ *   and a list-mode variant for documents-shared screens.
+ *   @doc-file avatar-group.usage.example.ts
+ * @doc-example Overflow
+ *   `kjMax` caps visible avatars; the remainder collapses into a "+N" chip.
+ *   @doc-file avatar-group.overflow.example.ts
+ * @doc-example Sizes
+ *   Group `kjSize` cascades onto every projected `<kj-avatar>` for a uniform pile.
+ *   @doc-file avatar-group.sizes.example.ts
+ * @doc-example Shapes
+ *   Group `kjShape` cascades to children; the +N chip mirrors it for a consistent silhouette.
+ *   @doc-file avatar-group.shapes.example.ts
+ * @doc-example List
+ *   `kjRole="list"` switches to a list landmark — use for "shared by" rows in docs UIs.
+ *   @doc-file avatar-group.list.example.ts
+ *
+ * @doc-aria
+ *   aria-label       — Count-aware label like "3 of 8 collaborators"; override via `kjAriaLabelOverride`
+ *   role             — Defaults to `img` (face-pile); set `kjRole="list"` for a true list landmark
+ *   aria-hidden      — Forced on the +N chip so the count isn't re-announced
+ *
+ * @doc-touch
+ *   Stacked avatars are decorative — they aren't tab stops. Pair the group
+ *   with an interactive trigger (button/link) sized ≥ 44×44 when clicking is
+ *   meaningful (e.g. opens a collaborator dialog).
+ *
+ * @doc-a11y
+ *   The face-pile is an `img` landmark with a count-aware accessible name so
+ *   AT users hear "3 of 8 collaborators" rather than every initial. Switch to
+ *   `role="list"` whenever the order/identity of each face matters
+ *   semantically. The overflow chip is always `aria-hidden` because the
+ *   group's name already conveys totality.
+ *
+ * @doc-related avatar,badge,tag
+ *
+ * @doc-css-var
+ *   --kj-avatar-size    — Avatar diameter. Sizes (xs/sm/md/lg/xl) override.
+ *   --kj-avatar-bg      — Avatar background. Defaults to --kj-bg-field; the +N chip inherits this too.
+ *   --kj-avatar-fg      — Avatar foreground (initials, fallback glyph). Defaults to --kj-fg-default.
+ *   --kj-avatar-radius  — Corner radius. `circle` shape pins it to 9999px; `rounded` swaps to --kj-radius-box.
+ *
+ * @doc-category Library/Data display
+ * @doc
+ * @doc-name avatar
+ * @doc-description Themed avatar facepile that stacks avatars with an overflow chip and an accessible count label.
+ * @doc-is-main
+ */
+@Component({
+  selector: 'kj-avatar-group',
+  standalone: true,
+  hostDirectives: [
+    {
+      directive: KjAvatarGroup,
+      inputs: [
+        'kjMax',
+        'kjTotal',
+        'kjSize',
+        'kjShape',
+        'kjAriaLabel',
+        'kjAriaLabelFormat',
+        'kjRole',
+        'kjAriaLabelOverride',
+      ],
+    },
+  ],
+  imports: [KjAvatarComponent],
+  template: `
+    <ng-content />
+    @if (overflowCount() > 0) {
+      <kj-avatar
+        class="kj-avatar-group-overflow"
+        aria-hidden="true"
+        [content]="overflowLabel()"
+        [shape]="chipShape()"
+      />
+    }
+  `,
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    'class': 'kj-avatar-group',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjAvatarGroupComponent {
+  /**
+   * Read-only handle to the composed `KjAvatarGroup` directive. The directive
+   * `provide`s itself under `KJ_AVATAR_GROUP`, so injecting the token returns
+   * the same instance and gives us access to `overflowCount`, `shape`, etc.
+   */
+  private readonly group = inject(KJ_AVATAR_GROUP);
+
+  protected readonly overflowCount = this.group.overflowCount;
+
+  protected readonly overflowLabel = computed(() => `+${this.overflowCount()}`);
+
+  /**
+   * Chip shape mirrors the group's default shape so the chip visually
+   * matches the avatars. `<kj-avatar>`'s own `shape` default is `'circle'`,
+   * which is also the group's default — so a missing group shape cleanly
+   * collapses to `'circle'`.
+   */
+  protected readonly chipShape = computed<'circle' | 'rounded'>(
+    () => (this.group.shape() as KjAvatarShape | undefined) ?? 'circle',
+  );
+}
+
+export type { KjAvatarGroupAriaLabelFormat };

package/src/avatar/avatar-group.usage.example.ts

@@ -0,0 +1,30 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { KjAvatarComponent } from './avatar';
+import { KjAvatarGroupComponent } from './avatar-group';
+
+/**
+ * Common avatar-group shapes — a capped face-pile with +N chip and a list-mode
+ * variant for "shared by" rows. Use this as the copy-paste starting point.
+ */
+@Component({
+  selector: 'kj-avatar-group-usage-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [KjAvatarGroupComponent, KjAvatarComponent],
+  styles: [`:host { display: flex; flex-direction: column; gap: var(--kj-space-md); }`],
+  template: `
+    <kj-avatar-group kjMax="3" kjTotal="7">
+      <kj-avatar content="AL" alt="Alice" />
+      <kj-avatar content="BO" alt="Bo" />
+      <kj-avatar content="CJ" alt="CJ" />
+      <kj-avatar content="DI" alt="Di" />
+    </kj-avatar-group>
+
+    <kj-avatar-group kjRole="list" kjSize="sm">
+      <kj-avatar content="EV" alt="Evan" />
+      <kj-avatar content="FA" alt="Fay" />
+      <kj-avatar content="GU" alt="Guo" />
+    </kj-avatar-group>
+  `,
+})
+export class KjAvatarGroupUsageExample {}

package/src/avatar/avatar.css

@@ -0,0 +1,58 @@
+@layer kj.component {
+  .kj-avatar {
+    --kj-avatar-size:   2.5rem;
+    --kj-avatar-bg:     var(--kj-bg-field);
+    --kj-avatar-fg:     var(--kj-fg-default);
+    --kj-avatar-radius: 9999px;
+
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: var(--kj-avatar-size);
+    height: var(--kj-avatar-size);
+    background: var(--kj-avatar-bg);
+    color: var(--kj-avatar-fg);
+    border-radius: var(--kj-avatar-radius);
+    overflow: hidden;
+    font: 0.875rem / 1 var(--kj-font-sans);
+    font-weight: 600;
+  }
+
+  /* `rounded` reads `--kj-radius-box-lg` (1rem default, declared in
+     `kj.base`) rather than `--kj-radius-box` because some themes (kouji,
+     bauhaus) set `--kj-radius-box` to 0 as a brutalist signature — falling
+     back to that would make `rounded` and `circle` look identical on those
+     themes. `--kj-radius-box-lg` stays unset by theme overrides, so the
+     toggle always produces a visible shape change. */
+  .kj-avatar[data-shape="rounded"] { --kj-avatar-radius: var(--kj-radius-box-lg); }
+
+  /* The host's `[hidden]` attribute (written by the avatar-group when a
+     child overflows `kjMax`) needs an explicit `display: none` because the
+     `inline-flex` declaration above wins against the UA `[hidden] { display:
+     none }` rule via selector specificity. Without this, "hidden" overflow
+     avatars still render and `kjMax` looks broken. */
+  .kj-avatar[hidden] { display: none; }
+
+  .kj-avatar[data-size="xs"] { --kj-avatar-size: 1.5rem; font-size: 0.6875rem; }
+  .kj-avatar[data-size="sm"] { --kj-avatar-size: 2rem;   font-size: 0.75rem; }
+  .kj-avatar[data-size="lg"] { --kj-avatar-size: 3rem;   font-size: 1rem; }
+  .kj-avatar[data-size="xl"] { --kj-avatar-size: 4rem;   font-size: 1.25rem; }
+
+  .kj-avatar-image {
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+    display: block;
+  }
+  .kj-avatar-image:not([data-loaded]) { opacity: 0; }
+
+  .kj-avatar-fallback {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+  .kj-avatar-fallback:not([data-visible]) { opacity: 0; pointer-events: none; }
+}

package/src/avatar/avatar.playground.ts

@@ -0,0 +1,95 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { KjAvatarComponent } from './avatar';
+import { KjAvatarGroupComponent } from './avatar-group';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+/**
+ * Playground state — module-scope signals. Targets the group facepile (main
+ * symbol) and exposes size / shape / max-visible / total / item count so the
+ * overflow chip and stacking can be probed.
+ */
+const size = signal<'xs' | 'sm' | 'md' | 'lg' | 'xl'>('md');
+const shape = signal<'circle' | 'rounded'>('circle');
+const max = signal<2 | 3 | 4 | 5>(3);
+const total = signal<4 | 6 | 8>(6);
+const itemCount = signal<3 | 4 | 5>(4);
+
+const PEOPLE: ReadonlyArray<{ content: string; alt: string }> = [
+  { content: 'AL', alt: 'Alice' },
+  { content: 'BR', alt: 'Bruno' },
+  { content: 'CY', alt: 'Cyrille' },
+  { content: 'DA', alt: 'Dara' },
+  { content: 'ED', alt: 'Eduardo' },
+];
+
+@Component({
+  selector: 'kj-avatar-playground',
+  standalone: true,
+  imports: [KjAvatarComponent, KjAvatarGroupComponent],
+  template: `
+    <kj-avatar-group
+      [kjMax]="max()"
+      [kjTotal]="total()"
+      [kjSize]="size()"
+      [kjShape]="shape()"
+    >
+      @for (p of visiblePeople(); track p.alt) {
+        <kj-avatar [content]="p.content" [alt]="p.alt" />
+      }
+    </kj-avatar-group>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjAvatarPlaygroundDemo {
+  protected readonly size = size;
+  protected readonly shape = shape;
+  protected readonly max = max;
+  protected readonly total = total;
+  protected readonly itemCount = itemCount;
+
+  protected visiblePeople(): typeof PEOPLE {
+    return PEOPLE.slice(0, itemCount());
+  }
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjAvatarPlaygroundDemo,
+  state: {
+    size: size as unknown as ReturnType<typeof signal>,
+    shape: shape as unknown as ReturnType<typeof signal>,
+    max: max as unknown as ReturnType<typeof signal>,
+    total: total as unknown as ReturnType<typeof signal>,
+    itemCount: itemCount as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    {
+      kind: 'chips',
+      name: 'size',
+      label: 'size',
+      options: ['xs', 'sm', 'md', 'lg', 'xl'],
+    },
+    { kind: 'chips', name: 'shape', label: 'shape', options: ['circle', 'rounded'] },
+    { kind: 'chips', name: 'max', label: 'max visible', options: [2, 3, 4, 5] },
+    { kind: 'chips', name: 'total', label: 'total', options: [4, 6, 8] },
+    { kind: 'chips', name: 'itemCount', label: 'items', options: [3, 4, 5] },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      size: string;
+      shape: string;
+      max: number;
+      total: number;
+      itemCount: number;
+    };
+    const attrs: string[] = [
+      `[kjMax]="${s.max}"`,
+      `[kjTotal]="${s.total}"`,
+      `kjSize="${s.size}"`,
+      `kjShape="${s.shape}"`,
+    ];
+    const children = PEOPLE.slice(0, s.itemCount)
+      .map((p) => `  <kj-avatar content="${p.content}" alt="${p.alt}" />`)
+      .join('\n');
+    return `<kj-avatar-group\n  ${attrs.join('\n  ')}\n>\n${children}\n</kj-avatar-group>`;
+  },
+};

package/src/avatar/avatar.ts

@@ -0,0 +1,123 @@
+import { Component, ChangeDetectionStrategy, ViewEncapsulation, computed, inject, input, TemplateRef } from '@angular/core';
+import { NgTemplateOutlet } from '@angular/common';
+import { KjAvatar, KjAvatarImage, KjAvatarFallback, KJ_AVATAR_GROUP, type KjAvatarShape } from '@kouji-ui/core';
+
+type KjAvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+/**
+ * Avatar component. Renders an image when `src` is provided; otherwise (or when
+ * the image fails to load) shows the `content` input. `content` accepts a plain
+ * string or a `TemplateRef` for richer markup (icon, sub-badge, etc.).
+ *
+ * @doc-example Default
+ *   The default playground — initials avatar at the default size.
+ *   @doc-file avatar.default.example.ts
+ * @doc-example Usage
+ *   The common shapes — image, initials fallback, sized, and a rounded square.
+ *   Use this as the copy-paste starting point.
+ *   @doc-file avatar.usage.example.ts
+ * @doc-example Sizes
+ *   xs / sm / md / lg / xl — `md` is the default.
+ *   @doc-file avatar.sizes.example.ts
+ * @doc-example With image
+ *   Bind `src` and `alt` — the alt also surfaces as a native hover tooltip.
+ *   @doc-file avatar.with-image.example.ts
+ * @doc-example Initials fallback
+ *   Project text into `content` for a graceful fallback when `src` is missing.
+ *   @doc-file avatar.initials.example.ts
+ * @doc-example Shapes
+ *   `circle` (default) or `rounded` — pick the silhouette that matches the surface.
+ *   @doc-file avatar.shapes.example.ts
+ *
+ * @doc-aria
+ *   alt           — Forwarded to the inner `<img>`; falls back to empty string when omitted
+ *   title         — Mirrors `alt` so hovering surfaces a native tooltip
+ *   data-size     — Mirrors the resolved size for theme/scope hooks
+ *   data-shape    — Mirrors the resolved shape for theme/scope hooks
+ *
+ * @doc-a11y
+ *   When `src` is set the inner `<img>` carries the user-supplied `alt`; an
+ *   empty alt (the default) marks it decorative so AT skips it — pair with a
+ *   visible name elsewhere. The fallback element is a `<span>` so it reads as
+ *   plain text rather than an image.
+ *
+ * @doc-related avatar-group,badge,icon
+ *
+ * @doc-category Library/Data display
+ * @doc
+ * @doc-name avatar
+ */
+@Component({
+  selector: 'kj-avatar',
+  standalone: true,
+  hostDirectives: [KjAvatar],
+  imports: [KjAvatarImage, KjAvatarFallback, NgTemplateOutlet],
+  template: `
+    @if (src(); as srcVal) {
+      <img kjAvatarImage class="kj-avatar-image" [src]="srcVal" [alt]="alt() ?? ''" />
+    }
+    <span kjAvatarFallback class="kj-avatar-fallback">
+      @if (isTemplate(content())) {
+        <ng-container *ngTemplateOutlet="$any(content())"></ng-container>
+      } @else {
+        {{ content() }}
+      }
+    </span>
+  `,
+  styleUrl: './avatar.css',
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    'class': 'kj-avatar',
+    '[attr.data-size]': 'resolvedSize()',
+    '[attr.data-shape]': 'resolvedShape()',
+    // Mirror `alt` to `title` so hovering the avatar shows a native tooltip.
+    // `alt` alone only surfaces to screen readers / fallback rendering.
+    '[attr.title]': 'alt()',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjAvatarComponent {
+  /**
+   * Optional `KjAvatarGroup` context. Avatars rendered inside a
+   * `<kj-avatar-group>` inherit `kjSize` / `kjShape` from the group when
+   * their own inputs are unset — matching the `@doc-example Sizes` claim
+   * that group size "cascades onto every projected `<kj-avatar>`".
+   */
+  private readonly group = inject(KJ_AVATAR_GROUP, { optional: true });
+
+  readonly src = input<string | undefined>(undefined);
+  readonly alt = input<string | undefined>(undefined);
+  /** Content shown when there is no `src`, or as a fallback if the image fails. */
+  readonly content = input<string | TemplateRef<unknown>>('');
+  /**
+   * Explicit avatar size. Leave unset to inherit from a parent
+   * `<kj-avatar-group kjSize="...">`; falls back to `'md'` when neither
+   * is set.
+   */
+  readonly size = input<KjAvatarSize | undefined>(undefined);
+  /**
+   * Explicit avatar shape. Leave unset to inherit from a parent
+   * `<kj-avatar-group kjShape="...">`; falls back to `'circle'` when neither
+   * is set.
+   */
+  readonly shape = input<KjAvatarShape | undefined>(undefined);
+
+  /** Effective size — explicit input wins, then group context, then `'md'`. */
+  protected readonly resolvedSize = computed<KjAvatarSize>(() => {
+    const own = this.size();
+    if (own) return own;
+    const fromGroup = this.group?.size() as KjAvatarSize | undefined;
+    return fromGroup ?? 'md';
+  });
+
+  /** Effective shape — explicit input wins, then group context, then `'circle'`. */
+  protected readonly resolvedShape = computed<KjAvatarShape>(() => {
+    const own = this.shape();
+    if (own) return own;
+    return this.group?.shape() ?? 'circle';
+  });
+
+  protected isTemplate(v: unknown): v is TemplateRef<unknown> {
+    return v instanceof TemplateRef;
+  }
+}

package/src/avatar/index.ts

@@ -0,0 +1,2 @@
+export * from './avatar';
+export * from './avatar-group';

package/src/badge/_examples/badge.default.example.ts

@@ -0,0 +1,18 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjBadgeComponent } from '../badge';
+
+@Component({
+  selector: 'kj-badge-default-example',
+  standalone: true,
+  imports: [KjBadgeComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `<kj-badge>New</kj-badge>`,
+})
+export class KjBadgeDefaultExample {}

package/src/badge/_examples/badge.sizes.example.ts

@@ -0,0 +1,25 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjBadgeComponent } from '../badge';
+
+@Component({
+  selector: 'kj-badge-sizes-example',
+  standalone: true,
+  imports: [KjBadgeComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        gap: 0.5rem;
+        align-items: center;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-badge size="xs">Extra small</kj-badge>
+    <kj-badge size="sm">Small</kj-badge>
+    <kj-badge size="md">Medium</kj-badge>
+    <kj-badge size="lg">Large</kj-badge>
+  `,
+})
+export class KjBadgeSizesExample {}

package/src/badge/_examples/badge.variants.example.ts

@@ -0,0 +1,24 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjBadgeComponent } from '../badge';
+
+@Component({
+  selector: 'kj-badge-variants-example',
+  standalone: true,
+  imports: [KjBadgeComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        gap: 0.5rem;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-badge variant="default">Default</kj-badge>
+    <kj-badge variant="secondary">Secondary</kj-badge>
+    <kj-badge variant="destructive">Destructive</kj-badge>
+    <kj-badge variant="outline">Outline</kj-badge>
+  `,
+})
+export class KjBadgeVariantsExample {}

package/src/badge/_examples/badge.with-dot.example.ts

@@ -0,0 +1,31 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjBadgeComponent } from '../badge';
+
+@Component({
+  selector: 'kj-badge-with-dot-example',
+  standalone: true,
+  imports: [KjBadgeComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        gap: var(--kj-space-sm);
+        flex-wrap: wrap;
+        align-items: center;
+      }
+      .success {
+        --kj-badge-dot-color: var(--kj-bg-success);
+      }
+      .warning {
+        --kj-badge-dot-color: var(--kj-bg-warning);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-badge dot variant="secondary" class="success">Active</kj-badge>
+    <kj-badge dot variant="secondary" class="warning">Pending</kj-badge>
+    <kj-badge dot variant="outline">Archived</kj-badge>
+  `,
+})
+export class KjBadgeWithDotExample {}