DEV Community: Alex

Not everything in an Angular library is a component: what's new in ng-prism 22.7

Alex — Sat, 31 Oct 2026 18:29:40 +0000

ng-prism 22.7 is out. If you haven't come across it yet: ng-prism is a component lab for Angular libraries, a Storybook alternative without story files. You put a @Showcase decorator on a component, the TypeScript compiler picks up inputs, outputs and types at build time, and the components render in the same document as the styleguide, without an iframe. The full tour has the details.

Voice: elevenlabs.io

This release got bigger than I planned. Most of it is about the parts of a library that aren't a single component: services, pipes, components that only work together with others, and components that only exist inside another one. Besides that the styleguide works on a phone now, it has a new look, accessibility violations can be accepted with a reason, and the perf plugin measures what you actually ship.

Services and pipes get their own pages

A real library usually has more than components. A service that shows notifications, a few pipes, provider functions that configure them. Until now none of that had a place in the styleguide. If you put @Showcase on an @Injectable, ng-prism treated it as a component and tried to render it, which never made much sense.

In 22.7 services and pipes are their own kind:

@Showcase({
  title: 'Time Ago',
  category: 'Formatting',
  setup: () => [provideTimeAgo],
})
@Pipe({ name: 'timeAgo' })
export class TimeAgoPipe implements PipeTransform {

They get their own sections in the sidebar, Services and Pipes, and their page has no canvas. There's nothing to render, so it's an API page: the description, a usage snippet you can copy, the examples from your JSDoc, the properties and methods of a service or the transform() overloads of a pipe, and cards for the types they use. {@link} and @see jump to those cards.

setup is the part I care about most. It lists the provider functions and injection tokens a consumer needs, and the usage snippet calls them in providers: [...]. So the page doesn't only tell you what the service has, it also tells you how to wire it up.

Components and directives get the same API page now. Inputs link to their types, outputs show their payload, documented methods are listed, and there's an "On this page" list next to it.

Have a look at the Notification Service and the Time Ago pipe in the demo.

Two things to know. The pages come from the JSDoc plugin, so you need jsDocPlugin() 22.7 or newer, otherwise services and pipes are only counted and you get a notice in the build. And a pipe has to be standalone with a readable name, otherwise it's left out with a warning.

Components that only work together

Some components don't make sense on their own. A form field without an input is an empty frame, and an input directive without its form field is a bare <input>. So far the best you could do was project some HTML into the form field. The input in there was plain markup, not your directive, so the form field never found its control.

In 22.7 a showcase can contain a real Angular template, and ng-prism compiles it. This is how the input directive in the demo shows up inside its form field:

@Showcase<InputDirective>({
  title: 'Input',
  category: 'Forms',
  host: { template: '<lib-form-field label="Name"><input libInput type="text" /></lib-form-field>' },
  variants: [
    { name: 'Default' },
    { name: 'Required', inputs: { required: true } },
    {
      name: 'With hint',
      host: { template: '<lib-form-field label="Name" hint="As on your ID"><input libInput /></lib-form-field>' },
    },
  ],
})

The directive is the subject, and the form field around it is real. Content queries and DI work the way they do in your app, so the form field finds its input like it would in a form. The controls still belong to the subject.

There are three fields for this:

template on a variant is the content of the subject, compiled instead of pasted in as HTML.
host: { template } puts the subject inside other markup. If more than one element matches, prism-subject marks the one you mean.
imports brings in classes from outside your library. Classes from your own library are imported automatically.

A related fix: a directive without a host now renders on the element its selector names. input[libInput] becomes <input libInput>, and void elements like <input> or <img> no longer break the build.

The limits: expressions in these templates have no context, so only literals and template reference variables work. Overlays that render into <body> aren't part of the composition. And if you have visual regression baselines for directives, look at them after the update, because some directives now render on a different element than before.

In the demo: the Input directive and the Form Field.

Parts

The opposite case are components that only ever live inside another one, like a list item or an option in a select. Their own page would show a list item floating alone on the canvas, which helps nobody.

Now such a component can say whose part it is:

@Showcase<ListItemComponent>({
  title: 'List Item',
  partOf: 'lib-list',
  description: 'One entry of a lib-list.',
})

A part has no page of its own. The parent's head shows a Parts chip that opens a card with the part's inputs and outputs, and the parent's API tab gets a Parts section. If somebody opens the part's old URL, they land on the parent.

partOf takes the parent's selector as a string, not the class. That way the part doesn't have to import its parent, which would end in an import cycle pretty quickly. A part has exactly one parent, there are no chains.

The List with its item in the demo.

The styleguide on a phone

Until now the styleguide was hard to use on a phone, which was annoying whenever somebody sent a link to a component. Up to 900 px width, and on touch screens up to 500 px height (a phone in landscape), the layout changes now:

The navigation opens full screen from a menu button.
The canvas gets the whole width, and the panel sits below it at about half the height. Tap the active tab and it folds away, drag the grip to resize it.
The header keeps what matters, the theme switch and the build info move into the menu.
Controls stack, touch targets are at least 40 px, and text fields use 16 px so iOS doesn't zoom in when you tap them.

The measuring tools stay out on a phone. Guides, rulers, the measuring tool and the viewport width need a mouse and a bigger screen to be useful.

The easiest way to try it is to open the demo on your phone.

Accepting an accessibility violation

ng-prism runs axe on every variant. Sometimes a violation is known and you've decided to keep it, for now or for good. So far the only option was to disable the rule, and then it disappeared from the panel. In 22.7 you can accept it, with a reason:

meta: {
  a11y: {
    accept: [
      {
        rule: 'color-contrast',
        reason: 'The hint grey (#6b7280) reaches 4.47:1 on the light ground, a hair under the 4.5:1 WCAG AA asks of small text.',
      },
    ],
  },
},

The reason is required. Accepted violations are still audited and listed under Accepted with their reason, they just don't count against the score. That's the difference to disable: you still see them, and so does the next person who looks at the component. meta.a11y is typed now too, so rules, disable and accept are checked by the compiler.

What axe can't decide on its own now shows up under Needs review instead of being dropped, and it doesn't count either. And the build gate is its own option, a11y.gate. If you leave it out, it's your thresholds like before. gate: false never fails the build, which is handy when your CI does the gating and the styleguide should still show the real numbers. The dev server doesn't stop over the gate anymore, it logs a warning and rebuilds when a new report comes in.

The Form Field's "With hint" variant in the demo has an accepted violation.

A new look

The colours changed. The primary colour is blue instead of violet, surfaces are slate and navy, and the header is a navy band in both themes. In the light theme the chrome is grey and the content white, it used to be the other way round. There's also a slow light moving through the header. If that bothers you, --prism-brand-motion: none stops it, and it holds still with reduced motion and in capture mode anyway.

For plugin authors the building blocks of the built-in panels are exported from @ng-prism/core now: prism-badge, prism-tabs, prism-segmented, prism-panel-toolbar, prism-list-row, prism-metric-card and the button directives. A panel built from them looks like the rest of the styleguide without copying any CSS. All scores also follow one rule now. a11y, coverage, VRT and perf use the same statusFor(), so "danger" means below 75 % of the threshold everywhere, not only in the header.

If you override theme tokens, check the deprecations below.

Bundle size that matches what you ship

The perf plugin used to measure the raw .ts file. That included the @Showcase config, all the JSDoc and every comment, and @ng-prism/core showed up as an import. So the better documented a component was, the worse it scored, which is the opposite of what I want.

Now the file is measured without the decorator and without comments, stripped the same way your published build is. On a real library the largest component went from 77 kb (critical) to 35 kb (warning), and four components that only warned because of their docs are well below 20 kb now. It still measures TypeScript source and not compiled output, so it's an estimate, but at least it's an estimate of your code.

Smaller things

An active state shows up as a chip in the variant ribbon, and you can clear it from there.
Every component opens on the Playground. The view doesn't carry over from the last component anymore.
The sidebar scrolls the open component into view and expands its group after a reload or when you follow a link.
The controls panel shows a Reset button as soon as an input differs from the variant.
A directive output with a payload no longer breaks the build with TS2345.
Stretch showcases fill the viewport width, and absolutely positioned elements stay inside their Overview cell.
The resize grips are visible and work with touch.
The docs start page has a one-minute tour.

Deprecations before 23

As usual, breaking changes within 22 come as deprecations first. These go away in 23.0.0, and the build tells you if you use them:

The theme tokens --prism-mark-nominal, --prism-mark-attention and --prism-mark-critical. Use --prism-success, --prism-warn and --prism-danger. Your overrides still carry over until 23.
--prism-spectrum, --prism-primary-from and --prism-primary-to. Use --prism-brand-gradient, or --prism-primary-fill for fills. Overrides of these have no effect anymore.
The variant of a panel badge. Use kind, tone and label.
A service or pipe with component fields like variants or host is still treated as a component until 23. Remove those fields, or move the demo to a component page.

One more thing if you read __PRISM_MANIFEST__ or use onComponentScanned in a plugin: services, pipes and parts aren't in components anymore. Services and pipes have their own lists and hooks, and parts sit under their parent's parts.

Upgrading

ng update @ng-prism/core

Update the plugins you use at the same time, and the JSDoc plugin in particular, because the new API pages come from there: ng update @ng-prism/core @ng-prism/plugin-jsdoc.

Demo: ng-prism.github.io/ng-prism/demo
Services and pipes in the docs: Showcasing services, Showcasing pipes
Compiled templates: Directive hosting
Release: github.com/ng-prism/ng-prism/releases/tag/v22.7.0
Repo: github.com/ng-prism/ng-prism

Which parts of your library still don't show up anywhere? Guards, interceptors, whole forms? I'd like to plan what comes next around real libraries, so let me know in the comments or open an issue.

Hover isn't a variant: what's new in ng-prism 22.6

Alex — Mon, 19 Oct 2026 21:31:25 +0000

Hover isn't a variant: what's new in ng-prism 22.6

ng-prism 22.6 is out. If you haven't come across it yet: ng-prism is a component lab for Angular libraries, a Storybook alternative without story files. You put a @Showcase decorator on a component, the TypeScript compiler picks up inputs, outputs and types at build time, and the components render in the same document as the styleguide, without an iframe. The full tour has the details.

The biggest change in this release is a new concept next to variants, called states. Besides that there's a Claude Code plugin for projects that use ng-prism, watch rebuilds that went from about 450 ms to about 60 ms, a few bug fixes and some deprecations ahead of version 23.

Hover as a variant didn't work out

In 22.5 I added pseudo to variants. pseudo: { hover: '.btn' } puts the button into :hover while the variant is shown, using the component's own CSS. That worked, and pretty quickly the button showcase in the demo looked like this:

variants: [
  { name: 'Filled', inputs: { variant: 'filled', label: 'Filled' } },
  { name: 'Outlined', inputs: { variant: 'outlined', label: 'Outlined' } },
  // …
  { name: 'Hovered', inputs: { variant: 'filled' }, pseudo: { hover: '.btn' } },
  { name: 'Pressed', inputs: { variant: 'filled' }, pseudo: { hover: '.btn', active: '.btn' } },
  { name: 'Focus visible', inputs: { variant: 'outlined' }, pseudo: { 'focus-visible': '.btn' } },
],

After a while this bugged me. These aren't really variants, they're the filled button again, just hovered. In the Playground they show up in the variant ribbon, and if you pick one, hover stays on while you play with the controls. They also only cover the combinations somebody wrote by hand. The filled button had a hover variant, the outlined one didn't. And hiding them from the ribbon wasn't an option either, because then they'd also disappear from the Overview and from the visual regression run, which is where they're actually useful.

Hover, pressed and focus describe what is happening to a component, not what kind of component it is. So in 22.6 they get their own axis.

States

A component now declares its states once, and every variant gets combined with them:

@Showcase<ButtonComponent>({
  title: 'Button',
  states: [
    { name: 'Hover', pseudo: { hover: '.btn' } },
    { name: 'Pressed', pseudo: { hover: '.btn', active: '.btn' } },
    { name: 'Focus visible', pseudo: { 'focus-visible': '.btn' } },
  ],
  variants: [
    { name: 'Filled', inputs: { variant: 'filled', label: 'Filled' }, bg: 'light' },
    { name: 'Outlined', inputs: { variant: 'outlined', label: 'Outlined' } },
    // … Elevated, Text, Icon Only, Disabled, Readonly, On dark
    {
      name: 'Full width',
      inputs: { variant: 'filled', label: 'Full width', fullWidth: true },
      canvasLayout: 'stretch',
      states: false,
    },
  ],
})

A state has a name and the same pseudo object you already know from variants. That's true for the whole component, or a selector (or a list of selectors) for the element the state belongs to, for example the inner <button> of a host component. The styling comes from your own CSS. ng-prism rewrites every rule that uses the pseudo-class, so :hover becomes :is(:hover, .prism-pseudo--hover), and sets that class on the targets. You don't write any extra styles.

With states: false a variant opts out. A full-width button in hover state wouldn't show anything new.

Variant.pseudo is still there and isn't deprecated. For a single special case, like a text field with specific inputs plus focus, it's still the simpler choice.

The Overview becomes a matrix

Until now the Overview tab showed all variants side by side. If a component declares states, it shows every variant in every state:

The Button with nine variants, Default plus three states. Each column header shows the selector of the state and how many variants it fits.

Each row is a variant, and its background and layout apply to the whole row. That's why On dark is dark in every column. If you click a cell, or focus it and press Enter, the Playground opens with exactly that variant and state. This works for every component now, with or without states.

Components without states keep the old Overview. And since the tab now counts cells instead of variants, a component with one variant and one state gets an Overview as well.

A state only shows up where the browser could produce it

In the Disabled row three cells are empty. Hover and Pressed say .btn has pointer-events: none, Focus visible says .btn is disabled. That's on purpose.

Technically ng-prism just sets a class. If your stylesheet draws a focus ring for that class, you'd get a focus ring on a disabled button, a state no user will ever see. For visual regression that's a real problem. The screenshot gets taken, becomes a baseline and is protected from then on, even though it shows something impossible.

So a state only gets applied where the browser could produce it on its own:

focus and focus-visible skip elements that are :disabled (also inside a <fieldset disabled>) or below [inert]. aria-disabled="true" doesn't count, because the browser can still focus that element. If the target is the whole component (true), the focusable elements inside it decide.
hover and active need an element that actually receives the pointer, so the target or one of its children must not have pointer-events: none. A disabled button without pointer-events: none does get hovered. If that cell then looks exactly like Default, good, because that's the test you want: the hover style doesn't leak into the disabled button.
focus-within isn't filtered. Without a browser API for focusability there's no reliable way to tell whether some child could take focus.

The selector counts too. The Chip's Remove hovered state targets .sg-chip__remove, and only removable chips render that button:

states: [{ name: 'Remove hovered', pseudo: { hover: '.sg-chip__remove' } }],

There's nothing to configure for this. Chips without a remove button get an empty cell with the reason.

There are six possible reasons: <target> matches nothing, <target> is disabled, <target> is inert, <target> has pointer-events: none, forces no state and states: false. If a state doesn't fit a single variant, it's almost always a typo in the selector. In that case the column header gets marked and you get one warning in the console.

One case took me longer than the rest. With hover-reveal CSS like .row:not(:hover) .actions { pointer-events: none }, whether .actions can be hovered depends on another forced class. An early version gave different results depending on how often the component had rendered. Now every pass measures the same way. It sets all forced classes, checks which targets are reachable and removes the class from the ones that aren't. So the first render, the one screenshot runners wait for, gives the same result as every later one.

States in the Playground

The variant ribbon only shows variants again. The State group in the tools menu now has a button for each declared state, above the :hover to :focus-within toggles that were already there. Pick Hover and it gets applied to whatever variant you're looking at.

The state stays on when you switch to another variant, so you can click through a whole column of the matrix. When you switch to another component, it's reset. The controls keep working, so you can change the label of a hovered button and it stays hovered. The state is also part of the URL. ?component=ButtonComponent&variant=1&state=0 opens the outlined button in hover state, here it is in the demo.

If a state doesn't fit the current variant, its button is dashed and the tooltip tells you why. You can still select it. It stays selected and kicks in as soon as the target exists:

On the Default chip there's nothing to hover. Turn on removable in the controls and the state applies.

Visual regression

ng-prism doesn't come with its own screenshot runner, because baselines, browser version and fonts belong to your CI. What it provides is a contract for driving the app, and 22.6 extends it. All of it is additive. Without states nothing changes, so existing runners and baselines keep working.

window.__PRISM_MANIFEST__ lists the states of each component as states: [{ name, index, pseudo }]. A variant that opts out has states: false.
?state=<index> selects a state, next to ?variant=.
With a state, data-prism-rendered is "<ClassName>:<variant>:<state>". Without one it stays "<ClassName>:<variant>".
If the state doesn't fit, .demo-wrap gets data-prism-excluded="<reason>". The runner should report the cell as excluded instead of taking a screenshot.
Capture mode (?capture=1) applies the state and leaves some space around the component, so focus rings outside its box don't get cut off.

Here's the loop from the docs, a bit shortened:

for (const comp of manifest.components) {
  for (const variant of comp.variants) {
    // The variant on its own (null), then in each state, unless it opted out.
    const cells = [null, ...(variant.states === false ? [] : (comp.states ?? []))];

    for (const state of cells) {
      const url = new URL(baseUrl);
      url.searchParams.set('component', comp.className);
      if (variant.index > 0) url.searchParams.set('variant', String(variant.index));
      if (state) url.searchParams.set('state', String(state.index));
      url.searchParams.set('capture', '1');
      await page.goto(url.toString());

      const key = `${comp.className}:${variant.index}${state ? `:${state.index}` : ''}`;
      await page.waitForSelector(`.demo-wrap[data-prism-rendered="${key}"]`);

      const excluded = await page.locator('.demo-wrap').getAttribute('data-prism-excluded');
      if (excluded !== null) {
        reportExcluded(comp, variant, state, excluded); // status: 'excluded', with the reason
        continue;
      }

      await page.evaluate(() => document.fonts.ready);
      const png = await page.locator('.demo-wrap').screenshot();
      // compare against e.g. 01-outlined--hover.png
    }
  }
}

The index of a state is its position in the source. If the scanner can't read an entry, the slot stays there as an empty state. A typo in one state can't move the next one onto the wrong baseline that way.

The VRT plugin reads two new optional fields from the report, stateIndex and stateName, and lists state captures next to their variant:

A Claude Code plugin for your library

Most coding agents have never seen ng-prism. Ask one to add a showcase and it guesses, usually with Storybook patterns. That's why the ng-prism repo is now also a Claude Code plugin marketplace. You don't have to clone anything, Claude Code fetches the plugin from GitHub:

claude plugin install ng-prism --marketplace ng-prism/ng-prism

Inside a session it's /plugin marketplace add ng-prism/ng-prism followed by /plugin install ng-prism@ng-prism. With --scope project the plugin gets enabled for the repo in .claude/settings.json. Your teammates still have to install it once themselves, but after that it loads automatically in that repo. Plugins from third-party marketplaces don't update on their own by default, so get new versions with claude plugin update ng-prism@ng-prism.

Skill	For
`ng-prism:showcase`	Writing or changing `@Showcase` configs, fixing `⚠ ng-prism:` build warnings
`ng-prism:setup`	`ng add`, `ng-prism.config.ts`, the official plugins, theming, publishing, upgrades
`ng-prism:write-plugin`	Your own plugin: build-time hooks, panels, controls, header widgets, sidebar decorations

The showcase skill doesn't stop after writing the config. It starts the styleguide, checks the build output for warnings and takes a screenshot of every variant it changed, using the Playwright from your project. So the agent actually looks at the result before saying it's done. The skills check which version of @ng-prism/core you have installed and go by its typings, and the plugin version follows the ng-prism releases.

Faster watch rebuilds

ng run my-lib:prism scans the library again on every save. The scanner already passed the previous ts.Program to ts.createProgram, but TypeScript only reuses a SourceFile if the compiler host returns the exact same object. The default host parses the file again on every call, so each rebuild parsed the whole program, Angular's typings included. Now there's a cache that keeps the parsed SourceFile as long as the file's mtime and size don't change.

I measured it on the demo library with 15 components, 100 rebuilds with one component change each:

	22.5	22.6
Warm rebuild, mean	452 ms	64 ms
Warm rebuild, p95	524 ms	102 ms
Memory (RSS)	~372 MB	~271 MB

There's a smaller one too. Reading the paths from your tsconfig no longer lists every file below it. In the demo workspace that went from 9.25 ms to 0.02 ms per rebuild, and in bigger workspaces the difference is bigger.

Fixes

Aliased inputs and outputs. A variant couldn't set an input like size = input('md', { alias: 'buttonSize' }) because Angular threw NG0303, and a directive host with an alias broke the styleguide build with NG8002. Variants and controls still use the member name, which is what InputsOf<T> expects, and ng-prism binds the public name. Aliases from a constant work too.
Named content slots. If a component had a named <ng-content select> before the default slot, variant content ended up in the wrong slots. Each key now goes into the slot its selector matches.
Libraries with only a primary entry point. If you set up such a library with ng add, the styleguide showed no components and no warning either. The primary entry point is now scanned together with the secondary ones.
Navigation. Back and forward between two components now restore the variant from the URL instead of jumping to variant 0, and switching the component from the Overview resets variant and state there as well.

Deprecations before 23

ng-prism versions follow the Angular majors, so a breaking change within 22 comes as a deprecation first. A few config and plugin options have existed since the first release without ever being used. 22.6 marks them as @deprecated, the build prints a note for each one you set, and they'll be removed in 23.0.0:

NgPrismConfig: ui, appComponent, themeStylesheet, headless
NgPrismPlugin.wrapComponent and a panel's position
perfPlugin(): thresholds, bundle.excludeImports, render, memory and the PERF_PLUGIN_CONFIG token

None of them ever did anything, so removing them from your config doesn't change any behaviour.

What states can't do

States are CSS pseudo-classes only: hover, active, focus, focus-visible and focus-within. Anything controlled by an input, like selected, expanded, loading or invalid, is still a variant.

The limits of pseudo from 22.5 still apply. A state after a pseudo-element (::part(label):hover) can't be forced, Shadow DOM isn't supported, and stylesheets from another origin can only be rewritten if they're served with CORS.

Also keep in mind that the matrix grows fast. 15 variants with 5 states means 90 screenshots per component. states: false and selectors that only match where they make sense help with that, but think about which states you really need.

Upgrading

ng update @ng-prism/core

Update the plugins you use at the same time, e.g. ng update @ng-prism/core @ng-prism/plugin-visual-regression. There's nothing to migrate, Variant.pseudo works exactly like in 22.5. If you want to switch to states, remove the hover, pressed and focus variants and declare the states once instead.

You can try all of this in the live demo, a small component library with all plugins enabled:

Button matrix: ng-prism.github.io/ng-prism/demo/?component=ButtonComponent&view=overview
States in the docs: ng-prism.github.io/ng-prism/#/guide/variants?id=states
Release notes: github.com/ng-prism/ng-prism/releases/tag/v22.6.0
Repo: github.com/ng-prism/ng-prism

I'm curious which states your components need that a CSS pseudo-class can't cover. Drag-over, open or loading maybe? I'd rather plan the next step around real components than around my own guesses, so let me know in the comments or open an issue.

What an Angular-native Storybook alternative actually looks like

Alex — Tue, 22 Sep 2026 11:22:54 +0000

ng-prism puts the showcase config on the component, extracts the rest with the TypeScript compiler, and renders into your document instead of an iframe. This is the whole tool, end to end, including the three things that shipped in v22.3: a visual-regression panel, an Overview contact sheet, and a UI rebuilt around a single density scalar.

Demo: dyingangel666.github.io/ng-prism/demo
Docs: dyingangel666.github.io/ng-prism
Repo: github.com/dyingangel666/ng-prism

The default, and what it costs

If you build an Angular component library, you probably run Storybook. Not because you compared options, because it is what exists. It is the thing with the addons, the CI recipes and the Stack Overflow answers, and choosing anything else means explaining yourself.

The price is quiet and you pay it every day. A parallel file tree of *.stories.ts that drifts from the components it describes. A second build toolchain living next to the Angular CLI, with its own config, its own cache and its own upgrade cadence. A preview iframe that isolates your component from the document, which is exactly where CDK overlays, MatDialog and anything else that portals to body want to be. And an abstraction, the component as a flat bag of args, that was designed for a framework generation where inputs were plain properties. I wrote about why that last one matters in the signal era already.

ng-prism is what I built instead, I wrote up the original motivation when it was still an experiment. It is not a port of Storybook's ideas to Angular; it starts from what Angular already gives you, a compiler that knows your types, a builder system that knows your workspace, and a component model built on signals, and asks how little tooling you can get away with on top.

What it is

You annotate the component. That is the whole authoring step.

import { Component, input, output } from '@angular/core';
import { Showcase } from '@ng-prism/core';

@Showcase<ButtonComponent>({
  title: 'Button',
  category: 'Inputs',
  description: 'Flexible button with five visual variants.',
  status: 'stable',
  tags: ['form', 'action'],
  variants: [
    { name: 'Filled', inputs: { variant: 'filled', label: 'Filled' } },
    { name: 'Outlined', inputs: { variant: 'outlined', label: 'Outlined' } },
    { name: 'Elevated', bg: 'dark', inputs: { variant: 'elevated' } },
  ],
})
@Component({
  selector: 'lib-button',
  template: `<button [class]="variant()" [disabled]="disabled()">{{ label() }}</button>`,
})
export class ButtonComponent {
  variant = input<ButtonVariantType>('filled');
  label = input('Button');
  disabled = input(false);
  clicked = output<void>();
}

The generic parameter is optional and worth taking: @Showcase<ButtonComponent> type-checks every variant's inputs against the component's actual input signals, so a renamed input breaks the build instead of silently rendering a default.

At build time a scanner walks your library's entry point with the TypeScript Compiler API and extracts what it needs: which exports carry @Showcase, what their inputs and outputs are called, what types they have, what the defaults are, what the JSDoc says. No runtime reflection, no emitDecoratorMetadata, no decorator evaluation. The decorator itself is a no-op marker, and a shipped transformer (ng-prism-strip) removes it from your compiled output, so publishing a library that uses ng-prism does not make your consumers install ng-prism.

Setup is one command, and it wires ng-prism's builders into your existing angular.json:

ng add @ng-prism/core
ng run my-lib:prism        # dev server on :4400
ng run my-lib:prism-build  # static styleguide for CI / Pages

The whole surface: navigation on the left with per-category roll-ups, the component head on top, the stage in the middle with a floating tool rail, and the addon dock below.

That is the Playground. Controls are generated from the input signals the scanner found and pushed through ComponentRef.setInput(), never property assignment, which on a signal input would overwrite the InputSignal with a raw value and break the component on the next render. Events are logged in the Events tab. The code snippet in the tool rail updates as you change inputs.

Three consequences of being Angular-native

No iframe. Components are instantiated through ViewContainerRef.createComponent() into the same document as the styleguide. Overlays land where they belong, focus trapping behaves, and cdkConnectedOverlay positions against the real viewport. This is the single thing I would not give up, and the a11y panel below is the clearest argument for why.

The build is your build. @ng-prism/core:serve and @ng-prism/core:build are Angular builders. They read your workspace, your tsconfig, your styles, your appProviders (provideHttpClient(), provideAnimationsAsync(), whatever your components need). There is no second bundler with a second opinion about your SCSS.

The docs write themselves. The JSDoc plugin turns the comments you already have into an API view, inputs with types and defaults, outputs, examples, @since and @see links, and it stays correct because it is derived from the source, not from a hand-written args table.

Accessibility is in the core, not in a plugin

An audit you have to remember to install is an audit that does not run. So the a11y panel is not one of the six official plugins, it ships with @ng-prism/core. The one thing you add is axe-core itself, and even that is a dynamic import, so it is only pulled in when the panel actually audits something.

A critical finding on a toggle switch, next to the toggle, not in a CI log three hours later. The green Tab 1 chip on the canvas is the keyboard tab-order overlay.

The audit runs against the rendered variant and re-runs, debounced, whenever an input changes, so it describes the thing you are editing rather than a snapshot from before your last change. Four tabs:

Violations the live axe-core report, sorted by impact (critical → serious → moderate → minor), passing rules listed below the failures, and a score ring that moves as you fix things.
Keyboard the tab-order overlay visible in the screenshot, plus focus-trap detection and missing-tabindex warnings.
ARIA Tree the accessible tree as the browser exposes it, with the computed accessible names.
Screen Reader what a screen reader would announce, as a list or a step-through player, with a perspective toggle that dims the canvas so you stop seeing what your users do not.

This is where the no-iframe decision pays off most. Dialogs, tooltips, menus and anything else riding the CDK overlay are where accessibility violations actually hide, and here they are in the same document the audit runs against instead of portalled out of an isolated preview frame.

When a rule is genuinely wrong for one component, you switch it off where the component is defined rather than in a global config file:

@Showcase({
  title: 'Button',
  meta: {
    a11y: { rules: { region: { enabled: false } } },
  },
})

And when informing you is not enough: the same audit runs headless. Drive the built styleguide variant by variant, run axe-core against .demo-wrap, write an a11y-report.json, and set thresholds in ng-prism.config.ts that fail the build, the header pill then carries the library-wide score into every PR preview. That is its own post.

What Storybook still does better

I would rather say this than have you find it out on day three.

Storybook has an ecosystem I cannot match: interaction tests with play() functions, Chromatic as a hosted visual-review service, MDX documentation, a decade of addons, and CI recipes for every provider. If your organisation ships React and Angular side by side, one tool across both is a real argument. If your workflow depends on component-level interaction testing inside the lab, Storybook has it and ng-prism does not, it gives you an Events panel and an external-tooling contract, which is a different and smaller thing.

ng-prism is smaller, more opinionated, and maintained by one person. It buys you: no story files, no second toolchain, no iframe, signal-native input handling, and plugin panels that read build-time reports. Pick accordingly.

New in v22.2, part I, the chrome went on a diet

The old header stack was three bands of ornament above the thing you actually came to look at: an app header, a component header with a breadcrumb and a title and a status chip and a description and tags, a row of four stat tiles, then a view tab bar, then the variant ribbon. On a laptop, the component had the bottom third of the screen.

v22.2 collapses that. The app header is 40px. The component head is one 36px row: breadcrumb, title, status, and then two buttons. Identity, selector, description, tags, variant count, lives behind an info popover. Measurement, coverage, a11y score, VRT diff, lives behind a gauge popover, with the head itself showing only the worst-deviating metric as a coloured chip.

One 36px row. The chip names the metric that deviates most; the popover has the rest.

Both popovers are the native Popover API, which means Escape, light dismiss and top-layer placement are browser behaviour rather than code I have to keep correct.

The band heights are not hard-coded pixels. Each is calc(<px> * var(--density)):

--band-header: calc(40px * var(--density)); /* app header    */
--band-head:   calc(36px * var(--density)); /* component head */
--band-rail:   calc(28px * var(--density)); /* variant ribbon */
--band-tabs:   calc(34px * var(--density)); /* addon tab bar  */

So the entire chrome rescales from one custom property. There is no density setting in a menu, because there does not need to be one:

export default defineConfig({
  theme: { '--density': '0.8' },
});

The canvas tools moved off the band they used to occupy and onto a floating rail over the stage, guides, rulers, background and zoom, and the live Angular template for the current inputs. The sidebar gained per-component status marks with a per-category roll-up (2/3 next to a category means two of its three components carry a mark), and plugins can contribute their own marks through a public extension point.

New in v22.2, part II, Overview, a contact sheet

The Playground is a viewfinder: one variant, big, with controls. That is the right tool for working on a variant and the wrong tool for the question "did the whole component survive the change I just made to the shared token file?", which needs all of them, at once, side by side.

Every cell renders a real instance of the variant on the background that variant declared, bg: 'dark' gets dark, an undeclared background gets the transparency checkerboard rather than a surface someone invented for it. A variant that stretches has no intrinsic width to compare against its neighbours, so it takes the whole row instead of a column.

There are deliberately no controls. Columns follow the window; everything else a cell shows is what the variant itself declared. The tab appears only when a component has at least two variants, a contact sheet of one is just a worse Playground, and never for a component that renders through a registered page, because those read their state from a single global renderer service and n cells would all show the same thing. That is a correctness argument, not a taste one.

The cells also share none of the Playground's bookkeeping: no output subscriptions, no prism:render:* performance marks, and crucially no data-prism-rendered marker, the selector external screenshot runners key on. One rendered thing means one marker.

New in v22.2, part III, visual regression, next to the component

Which brings us to the runner.

ng-prism does not ship a screenshot runner, and that is a decision rather than a gap. Capturing and comparing belongs to your CI container, because the container owns the three things that decide whether a diff is real: the baselines, the browser version, and the font stack. What ng-prism owns is the contract to drive the app and a rendering mode that makes the output deterministic.

That contract is small. Every variant is addressable by URL (?component=ButtonComponent&variant=1). The element to screenshot is .demo-wrap, and it is public API, not an implementation detail. And ?capture=1 puts the app into capture isolation mode: the canvas gets the whole viewport, zoom locks to 1, transitions and animations freeze document-wide, persisted session state is ignored, and every shell region that is not the canvas is hidden, by a structural rule rather than a selector list, so chrome changes like the tool rail moving do not invalidate a single baseline.

await page.goto(`${base}?component=${cls}&variant=${i}&capture=1`);
await page.waitForFunction(/* … data-prism-rendered … */);
await page.evaluate(() => document.fonts.ready); // fonts, not the marker, are the flake
const shot = await page.locator('.demo-wrap').screenshot();

Your runner compares those against baselines and writes a JSON report. @ng-prism/plugin-visual-regression reads that report at build time and renders it where the reviewer already is:

{
  "total": { "auditedVariants": 80, "unchanged": 74, "changed": 2, "new": 2, "score": 96 },
  "byVariant": [
    {
      "className": "ButtonComponent",
      "variantName": "Outlined",
      "variantIndex": 1,
      "status": "changed",        // unchanged | changed | size-mismatch | new | excluded
      "diffRatio": 0.102624,
      "baselinePath": "vrt/baseline/ButtonComponent/01-outlined.png",
      "currentPath": "vrt/current/ButtonComponent/01-outlined.png",
      "diffPath": "vrt/diff/ButtonComponent/01-outlined.png",
      "bg": "light",
      "baselineBg": "light"
    }
  ]
}

A few decisions in that panel I would defend:

The list is grouped, not flat. A library's variants are overwhelmingly unchanged, and fifteen identical cards bury the one you opened the panel for. Needs review is always open and ordered worst-news-first; Unchanged and Excluded start collapsed. When nothing needs review the rule inverts and the first group opens, two collapsed headers and no rows reads as a panel that failed to load.
new is neutral. A variant with no baseline has nothing to regress against. It sits in Needs review because only a human can accept a baseline, but it is never painted as a failure, and the tab badge stays amber rather than red.
A diff is never drawn below 1:1. Zoom offers Fit, 1×, 2×, 4×, and a downscaled diff mask is one you cannot trust.
Backgrounds are part of the comparison. The report carries both the run's background and the baseline's. When they differ, the panel says so, instead of leaving a reviewer to hunt a regression in an untouched component that simply got photographed on a different surface.

The library-wide score becomes a coloured pill in the header, thresholded in your config, so a deployed PR preview shows its own VRT state before anyone clicks into a component:

visualRegressionPlugin({
  reportPath: 'vrt-report.json',
  assetBaseUrl: 'assets/',
  thresholds: { score: 100 },
});

The rest of the plugin fan

Six official plugins, all registered the same way and all activated in both the build pipeline and the runtime:

Plugin	What it adds
JSDoc	The API view, inputs, outputs, examples, from your comments
Figma	Embedded design frame plus an in-browser design diff
Perf	Render profiling per variant
Box Model	Hover any element to inspect margin / border / padding / content
Coverage	Per-component test coverage read from an Istanbul or v8 summary
VRT	The report panel above

Accessibility is deliberately absent from that list, for the reason given above: it is in core, not something you have to remember to install.

Writing your own plugin is the same shape as the official ones: contribute panels, register custom controls for your own types, wrap every rendered component, or enrich the manifest at build time through onComponentScanned / onManifestReady.

Try it

ng add @ng-prism/core

Add @Showcase to one component, run ng run my-lib:prism, and you have a styleguide. Everything in this post is in the live demo, a small component library with all six plugins enabled, real coverage numbers and a real VRT report with a changed variant in it. Angular 20+ workspaces, tested against 20, 21 and 22; components need input() / output() signals.

Demo: dyingangel666.github.io/ng-prism/demo
Docs: dyingangel666.github.io/ng-prism
Repo: github.com/dyingangel666/ng-prism

If you try it on a real library, the feedback I want most is where it breaks, a component that will not render, a control type that has no editor, a builder assumption that does not hold in your workspace. Issues and PRs welcome, and a star helps more than it should.

A year of the EAA — does your component library's CI catch a11y violations yet?

Alex — Mon, 22 Jun 2026 14:51:14 +0000

The EAA is one year into enforcement, and most component libraries still ship without a single automated a11y check. Here is how I closed that gap in an Angular workspace, on two levels — live during development, and as a hard fail in CI.

A year in, and we are still flying blind

This week marks one year since the European Accessibility Act became enforceable on 28 June 2025. Member states started accepting complaints. Market surveillance authorities started asking questions. And a lot of teams that had been treating "we'll do an a11y pass before launch" as a strategy noticed, quietly, that there was no launch — there was a constant trickle of releases, and the a11y pass had never actually happened.

Component libraries are where this hits first. They ship dozens or hundreds of building blocks, every one of them potentially the thing that makes your product fail an audit. Ask yourself, honestly: how many components in your design system pass axe-core against WCAG 2.2 AA today? You don't know. Your CI doesn't know either.

This post is about how to fix that for an Angular library — on two layers, both wired into the same tool, and both runnable in under an hour of setup.

The two-layer model

There are two distinct moments where a11y feedback should land for a component library:

Dev-time. When I'm building a component variant, I want to see a11y violations as they happen, against the exact variant I'm rendering, without leaving my workflow.
CI-time. When a PR opens, I want every variant of every component re-audited and the build to fail loudly if the library regresses past a threshold.

These are not the same job. Dev-time is about catching cheaply. CI-time is about holding the line. You want both, and the tool I'll show — ng-prism, an Angular-native component showcase — wires both into the same workspace.

Layer 1: Live a11y in the component lab

ng-prism is a showcase tool similar in spirit to Storybook, but built around Angular's component model — I wrote about why I built it in an earlier post. You put @Showcase on a component, ng-prism scans your library, and you get a styleguide app with controls, theming, panels — and an A11y panel built into the core.

The panel runs axe-core against the rendered variant every time the variant or any input changes. It has four tabs:

Violations — the live axe-core report, sorted by impact (critical, serious, moderate, minor), with a score ring that updates in real time.
Keyboard — tab-order overlay, focus trap detection, missing-tabindex warnings.
ARIA Tree — the component's accessible tree as the browser sees it, with the computed accessible names.
Screen Reader — what a screen reader would announce, as a list or step-through player with a "screen-reader perspective" toggle that dims the canvas so you stop seeing what users don't.

You don't add a plugin to get this. It comes with @ng-prism/core. The only thing you ship into your workspace is axe-core as a peer dependency.

When a component needs a per-component override — a decorative icon that should not be audited, or a rule you know is wrong for this widget — you tag the showcase config:

@Showcase({
  title: 'Toast',
  meta: {
    a11y: {
      rules: {
        'color-contrast': { enabled: false },
      },
    },
  },
})
export class ToastComponent { /* ... */ }

This is the cheap layer. It catches the issues that would otherwise survive review because nobody pulled up DevTools and ran axe by hand. But the moment a contributor doesn't open the panel, the issue ships. That is what Layer 2 is for.

Layer 2: a CI step that fails loud

Here is the design call I want to spend a minute on: ng-prism does not ship a built-in audit CLI. I tried that, and pulled it out.

Component libraries live in different stacks. Some teams already have Playwright. Some run @axe-core/cli in a Docker step. Some have a custom headless harness for visual regression and want a11y bolted onto the same browser session. A built-in CLI would either lock teams into one of those, or balloon into a config surface that mirrors every option of all of them.

So instead of a CLI, ng-prism exposes a small contract — call it the External Audit API — and lets your team bring its own auditor. The contract has three anchors:

Anchor	What it is	Why
`window.__PRISM_MANIFEST__`	A global with `{ components: [{ className, variants: [{ name, index }] }], pages: [...] }` set by the running app.	Discovery. The auditor needs to know what to audit.
`?component=<className>&variant=<index>`	URL params the app reads on navigation.	Drive the app to a specific variant from the outside.
`[data-prism-rendered="<className>:<index>"]` on `.demo-wrap`	An attribute on the renderer host.	Render-completion marker — wait for this to flip before injecting axe.

A working auditor against this contract is small. Here is the core loop in Playwright (adapted from the real script I run against my own library, ~250 lines total including a tiny static server and threshold checks):

await page.goto(baseUrl, { waitUntil: 'networkidle' });
await page.waitForFunction(() => globalThis.__PRISM_MANIFEST__);
const manifest = await page.evaluate(() => globalThis.__PRISM_MANIFEST__);

for (const comp of manifest.components) {
  for (const variant of comp.variants) {
    const url = new URL(baseUrl);
    url.searchParams.set('component', comp.className);
    if (variant.index > 0) url.searchParams.set('variant', String(variant.index));

    await page.goto(url.toString(), { waitUntil: 'load' });
    await page.waitForFunction(
      ([key]) =>
        document
          .querySelector('.demo-wrap')
          ?.getAttribute('data-prism-rendered')
          ?.startsWith(key),
      [`${comp.className}:`]
    );

    await page.addScriptTag({ content: axeSource });
    const { violations } = await page.evaluate(async () => {
      const target = document.querySelector('.demo-wrap');
      const r = await globalThis.axe.run(target);
      return { violations: r.violations };
    });

    results.push({ className: comp.className, variant: variant.name, violations });
  }
}

The script writes an aggregated a11y-report.json at the end. ng-prism reads that file at build time and embeds the totals into the runtime manifest, so a coloured pill (green/orange/red) appears in the styleguide header — visible to anyone reviewing a deployed PR preview.

The thresholds live in your prism config:

// ng-prism.config.ts
import { defineConfig } from '@ng-prism/core';

export default defineConfig({
  a11y: {
    reportPath: 'a11y-report.json',
    thresholds: {
      score: 85,
      critical: 0,
      serious: 0,
      moderate: 5,
    },
  },
});

If the report breaches any threshold, the build fails. Not a warning, not a soft error — the pipeline goes red, the PR cannot merge.

Putting it in CI

The three steps for a GitHub Actions job (adapt to your runner of choice):

- run: npx nx run my-lib-prism:build       # 1. build the prism app
- run: npx nx run my-lib:audit-a11y        # 2. your audit script writes a11y-report.json
- run: npx nx run my-lib-prism:build       # 3. re-build to embed the report into the manifest

Two builds, because the report is generated against the first build and embedded by the second. The header pill renders only after step 3 — useful if you deploy PR previews, because reviewers can see the a11y score next to the components without clicking through every panel.

The audit step is your own script. If you don't want to write one, the Playwright snippet above plus argument parsing and threshold checks is roughly 200–250 lines and lives in scripts/. It's yours, in your repo, in JS or TS you can edit when your CI changes.

Why this fits Angular libraries specifically

A small note on tooling fit, because Angular libraries have one constraint that bites tooling all the time: dialogs and overlays. CDK Overlay, MatDialog, anything that portals to the body — they break in iframe-based component labs. ng-prism renders components directly into the host document via ViewContainerRef.createComponent(), so overlays land where they should, and the a11y audit sees them as real DOM. That matters because most of the WCAG violations I catch are in dialogs and floating UI — exactly the surfaces other tools tend to miss.

Beyond that: signal inputs and outputs work natively, the showcase config is just a decorator on the component (no separate story file), and a11y is in the core — not behind a plugin you have to remember to install.

Try it

ng add @ng-prism/core

Then add @Showcase to a component, run the prism builder, open the A11y panel, and watch the score ring move when you change a variant. From there, the External Audit API documented in docs/guide/accessibility.md is enough to write the CI script in an afternoon.

The repo: github.com/dyingangel666/ng-prism. If this post saved your team a CI compliance scramble, a star is appreciated — and issues, PRs, and "this works / this doesn't" reports are very welcome.

A year of the EAA is enough. Stop shipping component libraries that can't tell you their own a11y score.

Why I think Component-Driven Development needs a rethink in the Signal era

Alex — Mon, 18 May 2026 13:23:59 +0000

Component-Driven Development assumed a render model that signal-based Angular has quietly left behind. The tooling has not caught up, and I am not sure simply patching it will be enough.

The moment that made me write this

I was building ng-prism, an Angular-native component showcase tool I maintain, and I needed to update a component's inputs from a controls panel. The naive version looked roughly like this:

const ref = vcr.createComponent(ButtonComponent);
const instance = ref.instance;

instance.variant = 'primary';
instance.label  = 'Save';
ref.changeDetectorRef.detectChanges();

It works on a pre-signal component. On a signal-based component it quietly breaks the component. variant and label are no longer plain properties. They are InputSignal objects, callable as variant(). Angular stores the InputSignal as a plain class field; there is no defineProperty setter or proxy to intercept the write. So the assignment just overwrites the field reference with a string, and Angular never finds out. The next render then blows up the first time the template evaluates variant(), because variant is no longer a function. I verified this against @angular/core 21.2.0: createInputSignal() returns a plain function with a [SIGNAL] symbol attached, no setter trap in sight.

The fix is one line:

ref.setInput('variant', 'primary');
ref.setInput('label',   'Save');

That is the version that lives in ng-prism today, in the renderer effect that drives every showcase:

// packages/ng-prism/src/app/renderer/prism-renderer.component.ts
// Simplified; real version also handles content projection and unknown-input warnings.
effect(() => {
  const inputs = this.rendererService.inputValues();
  const ref    = this.componentRef;
  if (!ref) return;

  performance.mark('prism:rerender:start');
  for (const [key, value] of Object.entries(inputs)) {
    ref.setInput(key, value);
  }
  // setInput() already marks dirty and schedules CD. The explicit
  // detectChanges() here forces it to run synchronously so the
  // performance.mark below wraps the actual render, not just the
  // dirty-marking. Also keeps timings predictable under zoneless.
  ref.changeDetectorRef.detectChanges();
  performance.mark('prism:rerender:end');
});

This is a tiny detail, but it is the symptom of a much bigger thing. The way Component-Driven Development (CDD) thinks about a component (props in, render out, args table on the side) was modelled on a world where component inputs were plain properties. That world is gone in Angular. And once you stop assuming it, a lot of the tooling we have built over the last decade starts to look like it is solving the wrong problem.

The implicit model behind classic CDD

Look at what almost every CDD tool, Storybook included, has agreed on for years:

A component is a pure-ish function of its inputs.
Inputs are configured as a flat dictionary, the “args”.
A “story” is a specific value of that dictionary.
Changing args triggers a discrete re-render cycle.
Addons (a11y, viewport, knobs, controls) hook into that cycle.

In the pre-Hooks era this was the right abstraction. React class components had setState. Angular had @Input() decorators and ngOnChanges. Vue had options API. All of them had a clear, discrete moment where a property got assigned, the framework noticed, and the component re-rendered top-down. Args tables map onto that perfectly. Whatever knob you turn becomes a property assignment, which becomes an ngOnChanges call, which becomes a render.

This is also why Storybook’s args model felt so natural for so long. Args are properties. Properties are state. State drives render. Story = scenario = property snapshot.

It was a beautiful, simple model. It is also, for Angular today, the wrong abstraction.

What Signals actually changed

I do not want to retread the “signals are great” territory. What matters for CDD is more specific.

Inputs are no longer properties. An InputSignal is a callable getter. From outside the component, the only correct way to push a value into it is ComponentRef.setInput(name, value). There is no property to assign anymore. Tools that still build their abstractions on “assign this prop” are not even wrong yet, they just produce broken components.

Components are nodes in a reactive graph, not pure functions of inputs. Half of a real-world signal-based component is computed() derived state. Those derived signals are part of the component’s behaviour. They are not inputs, but they are also not opaque internal state. An args table cannot represent them. A story shapes inputs, not derived state.

Lifecycle work is increasingly split between explicit hooks and reactive subscriptions. ngOnInit and ngOnDestroy still exist and are still idiomatic for a lot of cases (subscriptions, teardown, one-shot setup). What has changed is that ngOnChanges is largely irrelevant for signal inputs, and a growing share of the work that used to live in lifecycle hooks now lives inside effect() or computed() that is read by the template. The places where work happens have multiplied, and a chunk of it fires on a much finer-grained schedule than mount → change → destroy. CDD tools that visualise lifecycle as those three states are visualising a real but shrinking slice of what the component actually does.

Re-renders are continuous, not cycle-based. Zoneless Angular still has ApplicationRef.tick() and a ChangeDetectionScheduler. What is gone is the implicit tick driven by zone.js intercepting every async operation. In a zoneless app, change detection runs because the scheduler decided to run it, which in practice is because a signal flagged a view dirty. From the outside that looks less like a single render cycle and more like a graph of signals notifying their dependents at fine granularity. An addon that says “re-run my check on each render cycle” has no clean event to listen to, because there is no single render cycle visible at the public surface of the component.

The pre-signal mental model is not catastrophically wrong. It is just lossy. And every layer of CDD tooling pays the price of that loss somewhere.

Where the tooling lags, concretely

Three examples I have hit while building ng-prism.

1. Controls and args still treat inputs as a flat property bag.

The Storybook args object and ng-prism’s own variant config both look like this:

{ variant: 'primary', label: 'Save', disabled: false }

That is fine as a starting state. It is wrong as a model of how the component actually consumes its inputs. A signal-based input has a default expression, can be required, can be tied through computed() into other state, and can be read multiple times per render. None of that is in the args object. The args object is a snapshot of a tree it cannot see.

2. A11y, perf, and visual-diff addons assume “render happened, now check”.

axe-core, layout measurements, screenshot capture: they all rely on a moment where the DOM has settled and you can inspect it. Angular does give you some primitives here. afterNextRender() fires once after the next render. afterRender() fires after every render. ApplicationRef.isStable exposes a stable-state observable. None of those quite match what an a11y or visual-diff addon actually wants, which is closer to “the reactive graph has been quiet for N milliseconds across multiple microtasks, and I am now safe to walk the DOM”. That concept does not exist as a framework primitive. So you debounce, you wait for animation frames, you hope. In ng-prism the built-in a11y audit runs after a 500ms debounce on signal changes (A11yAuditService.scheduleAudit, default debounceMs = 500), which works in practice but feels like a workaround. I am not sure a true “graph is quiescent” signal even makes sense in a system designed to update continuously.

3. The “scenario” unit is too coarse.

A Storybook story is one set of args. A ng-prism variant is one set of input values. Neither can express “this component embedded in a parent that emits a signal stream over time”. The interesting bug in a signal-based component is rarely the static case. It is the transition. It is the moment when an upstream computed() updates twice in the same microtask and your effect runs once instead of twice. You cannot represent that with { variant: 'primary' }.

What I tried in ng-prism, honestly

ng-prism started life with the same implicit model as Storybook. Components have inputs. Inputs have values. Variants are named tuples of input values. The decorator looks similar:

@Showcase({
  title: 'Button',
  variants: [
    { name: 'Primary', inputs: { variant: 'primary', label: 'Save' } },
    { name: 'Danger',  inputs: { variant: 'danger', disabled: true } },
  ],
})

What ng-prism does that I think is on the right track:

Uses setInput() for every input push, never property assignment. So at least the signal contract is respected. This is the absolute floor and a surprising number of Angular-adjacent tools still get it wrong.
Drives the rendering loop with effect() on a signal of input values, not with a render-cycle event. The renderer reacts to whatever upstream signal happens to change.
Treats the scanner as a build-time concern. Signal inputs are recognised via the TypeScript Compiler API at build time, so the runtime never has to read decorator metadata. The decorator itself is literally a no-op, just a marker.
Supports zoneless via an opt-in flag in the ng add schematic (--zoneless), which wires up provideZonelessChangeDetection() and drops zone.js from polyfills. The default still ships with zone.js, but nothing in the renderer depends on an implicit zone tick; change detection runs because something signal-shaped told it to.

What ng-prism does not solve yet, and where I think the whole category is still stuck:

The variant model is still a flat input snapshot. I cannot describe a component as “embedded in a parent that pushes this signal stream over 2 seconds”.
computed() derived state is invisible in the UI. You see the inputs you set. You do not see the graph that hangs off them. For some components, that graph is the interesting part.
The a11y, perf, and box-model panels all hook into renderer output the way an old addon would. They debounce. They do not subscribe to the actual reactive graph the component is part of.
The “code snippet” feature generates a template string from input values. It cannot show how the component would behave in a parent where one of those inputs is itself a signal.

I am being deliberate about this in the docs. I do not want ng-prism to claim a level of insight into signal-based components that it does not yet deliver.

What I think the next generation should look like

This is the speculative part, so take it as opinion.

I think the unit of CDD will stop being “the component with these props” and start being “the component embedded in a reactive context”. A scenario will look more like a tiny fixture: this component, mounted under this parent, with these signal sources feeding it, over time. Closer to a Playwright scenario than a Storybook story.

I think tooling will need to render the reactive graph, not just the visual output. For a serious component, the dependency graph between inputs, computed(), and effect() is the documentation. We render the box and the controls. We should also be able to render the graph.

I think the addon model needs to flip. Instead of hooking into a render lifecycle that no longer exists, addons should subscribe to specific signals. Visual diff subscribes to the renderedElement signal. A11y subscribes to the same. Perf subscribes to a “graph quiescent” signal that the framework would have to expose. None of this lives in Storybook’s current architecture, and bolting it on is not obviously the right answer.

And I think “args” as a UI metaphor has run its course. A signal-based component is not configured by setting properties. It is wired up. The control surface should reflect that.

Closing

I am not arguing that Storybook is bad, or that the people maintaining it have missed something obvious. They built the right tool for the framework world of 2018, and that tool became a standard. Standards lag by definition. That is fine.

What I am arguing is that the abstraction is starting to leak in ways that matter. Signal-based Angular is a different kind of component runtime, not a faster version of the old one, and the surface area that CDD tooling was designed against has changed underneath it.

I am building ng-prism partly to test that hypothesis in code, not just in prose. I am also fully prepared to find out that I am wrong, that an args table plus setInput() plus a debounce is good enough for 95% of cases, and that the rest is academic. Possible. But I do not think it is, and I would rather find out by building than by predicting.

If you have hit the same kind of friction, or you have a counter-example where the args model still maps cleanly onto a signal-heavy component, I would genuinely like to hear it. That is more useful than another “signals are great” thread.

ng-prism is open source on GitHub. Feedback and counter-examples especially welcome.

Why I Built ng-prism — An Angular-Native Storybook Alternative With Zero Story Files

Alex — Sat, 02 May 2026 19:03:21 +0000

TL;DR: ng-prism lets you showcase Angular components by adding a single decorator to the component class itself. No story files, no parallel file tree, no framework mismatch. Just Angular.

The Problem Every Angular Team Knows

If you've ever maintained a Storybook setup for an Angular component library, you know the drill: for every component you write, you also write a .stories.ts file. Then you keep both in sync. Then someone renames an input, the stories break silently, and nobody notices until the designer opens Storybook two sprints later.

Storybook is a fantastic tool — but it was born in the React ecosystem. Angular support has always been a second-class citizen. The CSF format doesn't feel natural in Angular. The iframe rendering breaks MatDialog, CDK overlays, and portals. The webpack/Vite configuration is yet another build system you have to understand alongside the Angular CLI.

I wanted something different. Something that feels like Angular because it is Angular.

Introducing ng-prism

ng-prism is a lightweight component showcase tool built from the ground up for Angular. The core idea is radical in its simplicity: you annotate your component with a @Showcase decorator, and ng-prism discovers it at build time via the TypeScript Compiler API.

No story files. No parallel file tree. The documentation lives where the code lives.

  import { Showcase } from '@ng-prism/core';                                                                                                                                                                   
  import { Component, input, output } from '@angular/core';

  @Showcase({
    title: 'Button',                                                                                                                                                                                             
    category: 'Atoms',                                                                                                                                                                                         
    description: 'The primary action button.',
    variants: [                                                                                                                                                                                                  
      { name: 'Primary', inputs: { label: 'Save', variant: 'primary' } },
      { name: 'Danger', inputs: { label: 'Delete', variant: 'danger' } },                                                                                                                                        
      { name: 'Ghost', inputs: { label: 'Cancel', variant: 'ghost' } }                                                                                                                                         
    ],                                                                                                                                                                                                           
  })                                                                                                                                                                                                           
  @Component({                                                                                                                                                                                                   
    selector: 'lib-button',                                                                                                                                                                                    
    standalone: true,                                                                                                                                                                                            
    template: `<button [class]="variant()">{{ label() }}</button>`
  })                                                                                                                                                                                                             
  export class ButtonComponent {                                                                                                                                                                               
    label = input.required<string>();                                                                                                                                                                            
    variant = input<'primary' | 'danger' | 'ghost'>('primary');
    clicked = output<void>();                                                                                                                                                                                    
  }

That's it. Run ng run my-lib:prism, and you get a fully interactive styleguide with variant tabs, a live controls panel, event logging, and code snippets — all extracted from your actual component at build time.

How It Works Under the Hood

ng-prism doesn't guess your component's API. It reads it. At build time, a custom Angular Builder kicks off a pipeline:

TypeScript Compiler API scanner — Parses your library's entry point, walks the AST, and extracts every component annotated with @Showcase. It reads input() and output() signal declarations, infers types, detects defaults, and builds a complete component manifest.
Plugin hooks — Registered plugins can enrich the scanned data (e.g., extracting JSDoc comments, injecting Figma URLs from metadata).
Runtime manifest generation — The pipeline produces a TypeScript file with real import statements pointing to your actual component classes. No JSON serialization, no runtime reflection.
Angular Dev Server — The builder delegates to @angular-devkit/architect, so you get the Angular dev server you already know — HMR, source maps, the works.

The result: your styleguide is a regular Angular app. No iframe. Components render in the same document context. MatDialog? Works. CDK Overlay? Works. CSS custom properties from a parent theme? Inherited naturally.

Signal-Native From Day One

ng-prism was built for Angular 21+ and the signal API. It understands input(), input.required(), and output() natively. The controls panel automatically generates the right control widget for each

input type:

string → text field
boolean → toggle
number → number input
Union types like 'primary' | 'danger' → dropdown
Complex types → JSON editor

When you change a value in the controls panel, it flows through Angular's signal system. There's no @Input() decorator support — and that's by design. If you're starting a new component library in 2026, you should be using signals.

Built-In Accessibility Auditing

Accessibility isn't a plugin in ng-prism — it's a core feature. The built-in A11y panel provides four perspectives on every component:

Violations — axe-core audit with a visual score ring, sorted by impact severity
Keyboard Navigation — Tab order visualization with overlay indicators
ARIA Tree — The accessibility tree as the browser sees it
Screen Reader Simulation — Step through your component the way a screen reader would, with play/pause navigation

Switch to "Screen Reader" perspective in the toolbar, and the canvas dims while SR annotations overlay your component. It's a first-class development tool, not an afterthought.

Plugin Architecture — Extend Everything

ng-prism follows a Vite-style plugin model. A plugin is a plain object with optional hooks for both build time and runtime:

  import type { NgPrismPlugin } from '@ng-prism/core/plugin';                                                                                                                                                  

  export function myPlugin(): NgPrismPlugin {
    return {                                                                                                                                                                                                     
      name: 'my-plugin',                                                                                                                                                                                       

      // Build-time: enrich scanned component data
      onComponentScanned(component) {                                                                                                                                                                            
        component.meta = { ...component.meta, myData: extractSomething(component) };                                                                                                                           
      },                                                                                                                                                                                                         

      // Runtime: add a panel to the UI                                                                                                                                                                          
      panels: [{                                                                                                                                                                                               
        id: 'my-panel',
        label: 'My Panel',                                                                                                                                                                                       
        loadComponent: () => import('./my-panel.component.js').then(m => m.MyPanelComponent),
        position: 'bottom',                                                                                                                                                                                      
        placement: 'addon',                                                                                                                                                                                    
      }],                                                                                                                                                                                                        
    };                                                                                                                                                                                                         
  }

Official Plugins

@ng-prism/plugin-jsdoc — Extracts JSDoc comments at build time and generates structured API documentation, including parameter tables
@ng-prism/plugin-figma — Embeds Figma designs as interactive iframes to enable direct visual comparison with components
@ng-prism/plugin-box-model — Overlays CSS box model dimensions directly on rendered components for layout inspection
@ng-prism/plugin-perf — Profiles initial render and re-render performance using the browser Performance API
@ng-prism/plugin-coverage — Displays per-component test coverage based on Istanbul/V8 reports

Plugins lazy-load their components, so they don't bloat your initial bundle.

Setup in Two Minutes

  ng add @ng-prism/core

The schematic asks which library you want to showcase, creates a prism app project, wires up the builder targets in angular.json, and generates a config file. Then:

  ng run my-lib:prism

Your styleguide is running at localhost:4200. For the config, you get a typed prism.config.ts:

  import { defineConfig } from '@ng-prism/core';                                                                                                                                                               
  import { jsDocPlugin } from '@ng-prism/plugin-jsdoc';
  import { figmaPlugin } from '@ng-prism/plugin-figma';

  export default defineConfig({
    plugins: [                                                                                                                                                                                                   
      jsDocPlugin(),                                                                                                                                                                                           
      figmaPlugin()
    ],
    theme: {
      '--prism-primary': '#6366f1',
      '--prism-primary-from': '#6366f1',
      '--prism-primary-to': '#8b5cf6'                                                                                                                                                                            
      // ...
    }                                                                                                                                                                                                            
  });

Watch Mode

The serve builder watches your library sources and config file. Change a component, add a @Showcase decorator, modify an input — the manifest regenerates, and the Angular dev server picks up the change. No restart needed.

Component Pages & Custom Pages

Not everything fits neatly into a per-component showcase. Sometimes you need a "Patterns" page showing how multiple components compose, or a color token overview.

ng-prism supports Component Pages — free-form Angular components registered alongside your showcased components. They're defined in your main.ts via providePrism():

  import { PrismShellComponent, providePrism, componentPage } from '@ng-prism/core';                                                                                                                           
  import { ButtonPatternsPageComponent } from './pages/button-patterns.page.js';                                                                                                                                 

  bootstrapApplication(PrismShellComponent, {                                                                                                                                                                    
    providers: [                                                                                                                                                                                                 
      providePrism(manifest, config, {                                                                                                                                                                         
        componentPages: [
          componentPage({
            title: 'Button Patterns',
            category: 'Atoms',                                                                                                                                                                                   
            component: ButtonPatternsPageComponent,
          }),                                                                                                                                                                                                    
        ],                                                                                                                                                                                                     
      }),
    ],
  });

For static pages that don't need Angular components, use Custom Pages directly in prism.config.ts:

  export default defineConfig({                                                                                                                                                                                
    pages: [                                                                                                                                                                                                     
      { type: 'custom', title: 'Changelog', category: 'Meta', data: { version: '2.1.0' } },
    ],                                                                                                                                                                                                           
  });

Both appear in the sidebar navigation alongside regular components.

Content Projection & Directive Hosting

Real-world components use <ng-content>. ng-prism handles this with a content property on variants:

  @Showcase({                                                                                                                                                                                                  
    title: 'Card',                                                                                                                                                                                               
    variants: [{
      name: 'With Header',                                                                                                                                                                                       
      content: {                                                                                                                                                                                               
        '[card-header]': '<h3>Title</h3>',
        'default': '<p>Body content</p>'
      }                                                                                                                                                                                                          
    }]
  })

Need to showcase a directive instead of a component? Use the host property to specify what element it attaches to — either a plain HTML string or another Angular component.

Why Not Just Use Storybook?

Storybook is mature, battle-tested, and has a massive ecosystem. If it works for your team, keep using it. But if you've felt the friction of:

Maintaining a parallel .stories.ts file tree that drifts out of sync
Fighting iframe restrictions when your component uses overlays or portals
Configuring a separate build system (webpack/Vite) alongside the Angular CLI
Wrapping Angular-specific patterns (dependency injection, signals) in framework-agnostic abstractions

…then ng-prism might be worth a look. It doesn't try to be framework-agnostic. It's Angular, all the way down.

The Road Ahead

ng-prism is open source under the MIT license and follows Angular's versioning: @ng-prism/core@21.x targets Angular 21. The current release is v21.6.1. Why already v21.6.1? Because we already use it in my company for our component library, so it's already battle-tested.

What's coming next:

More official plugins
CI integration — Manifest validation in your pipeline (e.g. ensuring every public component has a @Showcase decorator)
Design token documentation — Automatic token overview extracted from SCSS / CSS custom properties
Export — Share your component catalog as a PDF or static HTML page

Get Started

🔗 Demo
📖 Docs
📦 npm install @ng-prism/core

dyingangel666 / ng-prism

Lightweight Angular-native component showcase — no story files needed.

ng-prism

A component showcase for modern Angular, without story files You add one decorator to your component. ng-prism picks it up at build time and generates live controls, code snippets and docs from it.

Live demo · Documentation

Same button, two approaches

Storybook	ng-prism
// button.stories.ts (separate file) import type { Meta, StoryObj } from '@storybook/angular'; import { ButtonComponent } from './button.component'; const meta: Meta<ButtonComponent> = { title: 'Atoms/Button', component: ButtonComponent, argTypes: { variant: { control: 'select', options: ['primary', 'secondary', 'danger'] } } }; export default meta; type Story = StoryObj<ButtonComponent>; export const Primary: Story = { args: { variant: 'primary', label: 'Click me' } }; export const Danger: Story = { args: { variant: …

Storybook

ng-prism

// button.stories.ts (separate file)
import type { Meta, StoryObj } from '@storybook/angular';
import { ButtonComponent } from './button.component';
const meta: Meta<ButtonComponent> = {
    title: 'Atoms/Button',
    component: ButtonComponent,
    argTypes: {
        variant: {
            control: 'select',
            options: ['primary', 'secondary', 'danger']
        }
    }
};
export default meta;
type Story = StoryObj<ButtonComponent>;

export const Primary: Story = {
    args: { variant: 'primary', label: 'Click me' }
};
export const Danger: Story = {
    args: { variant:

…

View on GitHub

                                                                                                                                                                        </p>

If you're building an Angular component library and want your showcase to feel like Angular — give ng-prism a try. Star the repo if you find it useful, and feel free to open issues or contribute plugins.