phenixdigital/phoenix_storybook

Phoenix Storybook is a library for Phoenix applications that provides a visual interface for documenting, testing, and developing UI components. It allows developers to define component variations via a structured DSL, render them in an isolated playground, and organize them into a navigable tree with custom theming and dark mode support. The system integrates with the Phoenix asset pipeline, serving precompiled guides and dynamically rendered component previews while ensuring style isolation from the host application.

26 changes.

This period focused on the major v1.5.0 release, which involved renaming the project to Phoenix Storybook and upgrading core dependencies to Phoenix 1.8 and LiveView 1.2. The frontend was significantly modernized by migrating to Tailwind CSS v4, implementing a new theming system with dark mode support, and refactoring the JavaScript architecture. Additionally, the release introduced new Mix tasks for installation and development, alongside comprehensive test coverage for the updated content tree and configuration logic.

26 changes.

This period marks the initial release of the PhoenixStorybook library, establishing its core API, rendering engine, and Storybook DSL. The work focused on building foundational features such as unified icon rendering, CSP-compliant layouts, and precompiled guide support, while simultaneously refactoring the UI to prevent style conflicts. Comprehensive test coverage was added across all modules to ensure stability and correct behavior of the new components and helpers.

The Storybook UI now includes dedicated layout templates (root, live, and iframe variants) that properly handle Content Security Policy (CSP) by applying nonces to all script and style tags. Additionally, a new favicon template is introduced, providing standard icons (apple-touch-icon, 32x32, 16x16, mask-icon) and manifest links, all served with appropriate CSP nonces to prevent browser blocking.

_lib/phoenix\storybook/templates · high confidence

The generator now includes a new example story (\core\_components.story.exs\) that demonstrates the usage of Phoenix core components. This example showcases a user table and a form for adding users, utilizing components like \.table\, \.header\, \.input\, and \.button\ to provide a concrete reference for users integrating Phoenix Storybook with their applications.

priv/templates/phx.gen.storybook/examples · high confidence

The application now includes standard web manifest files (site.webmanifest, browserconfig.xml) and a Safari pinned-tab SVG icon in the static favicon directory. These additions enable proper rendering of the site icon on mobile home screens, in browser tabs, and within the Windows tile interface, improving the visual identity across different platforms and devices.

priv/static/favicon · high confidence

The repository is initialized with essential configuration files for the Phoenix Storybook project, including a Credo linter configuration (.credo.exs), a Biome JavaScript formatter configuration (biome.json), and a Coveralls coverage settings file (coveralls.json). The Elixir formatter (.formatter.exs) is updated to import Phoenix dependencies, use the LiveView HTML formatter, and export local function definitions. Documentation and metadata are added via new CONTRIBUTING.md, LICENSE.md, and a comprehensive CHANGELOG.md, while the README.md is rewritten to reflect the project's new name (Phoenix Storybook), installation instructions via Igniter, and configuration options. Additionally, the .gitignore is expanded to exclude coverage artifacts, compiled static assets, and IDE-specific files.

(repo-wide) · high confidence

The \lib/phoenix\_storybook.ex\ file has been added, introducing the core module and \BackendBehaviour\ for the Phoenix Storybook library. This change establishes the foundational API for integrating storybook functionality into Phoenix applications, including configuration merging, story compilation modes (lazy and eager), and content tree management.

lib · high confidence

Added the \mix dev.storybook\ task to streamline local development by automatically setting up the Phoenix Storybook dependency's assets, and introduced \mix phx.gen.storybook\ to generate Storybook scaffolding (backend, assets, and example stories) with instructions for manual setup. Additionally, a new \mix igniter.install phoenix\_storybook\ task was added to automatically apply the Storybook installation and configuration changes to a Phoenix application when Igniter is available.

lib/mix · high confidence

The storybook now uses a structured DSL for defining stories, introducing dedicated structs for attributes (\Attr\), slots (\Slot\), and variations (\Variation\/\VariationGroup\) to populate the Playground tab. Component documentation is now automatically fetched from source and rendered as HTML, with options to strip LiveView-specific attributes and slots. Story files (\.exs\) are validated at compile time for correct types and consistency, and sidebar organization is enhanced via optional \index.exs\ files that allow custom folder names, icons, and manual sorting.

_lib/phoenix\storybook/stories · high confidence

The Storybook playground now logs user interactions (events, params, and assigns) by attaching to Phoenix telemetry for LiveView and LiveComponent handle\_event stops. These events are broadcast over PubSub to the specific playground instance, enabling the event log UI to display a history of actions taken within the preview.

_lib/phoenix\storybook/events · high confidence

The storybook now provides a unified \Icon\ component that supports FontAwesome, HeroIcons, and local icons, allowing users to configure icons via a standardized tuple format (e.g., \{:fa, "book"}\ or \{:hero, "cake"}\). This capability is integrated into the \TabNavigation\ component, which now accepts icon configurations in its tab tuples to display icons alongside tab labels, supporting both pill and default tab variants.

_lib/phoenix\storybook/components · high confidence

The bundled JavaScript file \dist/js/app.js\ has been deleted from the distribution. This file previously contained the Phoenix LiveView client-side logic, including event handling, upload management, and DOM binding utilities. Its removal indicates that the application no longer serves this specific bundled client script, likely due to a shift in how LiveView assets are loaded or a restructuring of the frontend build process.

dist/js · high confidence

The library has been renamed from \phx\_live\_storybook\ to \phoenix\_storybook\, requiring users to update their module references and router configurations. The \PhoenixStorybook.Router\ now provides a \live\_storybook/2\ macro that sets up LiveView sessions and routes for the storybook interface, including support for optional CSRF tokens and custom asset paths. A new \PhoenixStorybook.CoreComponents\ module introduces a \kbd/1\ component for rendering keyboard keys and standardizes form input helpers, while the \PhoenixStorybook.Web\ module has been refactored to use \Phoenix.Component\ and \Phoenix.HTML\ imports directly, replacing the previous \Phoenix.View\-based structure.

_lib/phoenix\storybook · high confidence

The project has removed the legacy Tailwind CSS v3 configuration file (tailwind.config.js), which previously defined content paths and a 'lsb-' prefix. This change accompanies the migration to Tailwind CSS v4 syntax and the adoption of a new 'psb-' CSS prefix, as indicated by the commit history. Additionally, a new Biome configuration file (biome.json) has been added to handle JavaScript linting and formatting, while CSS linting is disabled to accommodate the non-standard Tailwind v4 syntax.

assets · high confidence

The \PhoenixStorybook.LayoutView\ module has been introduced to manage the storybook's HTML structure, enabling users to customize the UI via a \theme\_path\ configuration option and supporting configurable script types and FontAwesome CSS paths. This view also implements asset fingerprinting (MD5 hashes) for JS and CSS files to ensure proper cache busting, and adds support for Content Security Policy (CSP) nonces on script, style, and image tags.

_lib/phoenix\storybook/views · high confidence

The Storybook dashboard now uses a dedicated \JSAssets\ plug to serve bundled JavaScript files (including Phoenix and Phoenix Live View assets) instead of the previous method. This change introduces MD5 content hashing for cache-busting URLs and supports optional gzip compression of the served assets when the \:gzip\_assets\ application environment is enabled. An \AssetNotFoundController\ has also been added to handle invalid asset requests with a proper 404 response.

_lib/phoenix\storybook/controllers · high confidence

The frontend now includes dedicated CSS import files for the documentation layout, a global reset, and the welcome page, all scoped under the \.psb\ namespace to ensure consistent styling. These additions provide structured typography, spacing, and code-block rendering for documentation content, establish a baseline reset for HTML elements, and define specific visual styles for the welcome page interface.

assets/css/imports · high confidence

The Storybook interface components (Sidebar, Search, StoryLive, VisualTestLive, and ErrorHTML) have been refactored to namespace all CSS classes, IDs, and JS hooks under the \psb-\ prefix (e.g., \psb-search-container\, \PhoenixStorybook.SearchHook\). This prevents silent overrides and conflicts with the host application's styles and event handlers. The UI now uses a consistent \psb:\ Tailwind prefix for styling, and the search modal, sidebar navigation, and error pages are fully integrated with this new namespacing scheme.

_lib/phoenix\storybook/live · high confidence

The \priv/templates/phx.gen.storybook\ generator templates have been updated to align with Phoenix 1.8 and Tailwind v4. The generated Storybook configuration now supports a dedicated \theme\path\ for customizing the UI chrome via prefixed \psb:\\ Tailwind utilities and CSS variables, allowing users to recolor and reskin the sidebar and header. The generated CSS files now use Tailwind v4 syntax (e.g., \@import "tailwindcss" source(none)\) and include a reference stylesheet to make \psb:\ utilities available without emitting duplicate CSS. Additionally, the welcome page template has been refreshed with improved mobile styling and updated documentation links.

priv/templates/phx.gen.storybook · high confidence

The guides system now precompiles markdown files into HTML at compile time using the MDEx library, rather than rendering them at runtime. This change improves performance by avoiding the need for end-users to install the MDEx dependency and keeps guide assets out of the application's private directory. The rendering logic is now encapsulated in the new \PhoenixStorybook.Guides.Macros\ module, which generates static markup functions for each guide file, and this process is gated by the \PhoenixStorybook.enabled?\ check to ensure it only runs when the storybook is active.

_lib/phoenix\storybook/guides · high confidence

The story documentation view now supports collapsible 'Read more' sections for longer component descriptions and allows configuration to preserve or strip attributes and slots from the rendered documentation. The playground experience has been enhanced with a new HTML source tab for stateless components, improved code formatting, and better handling of live component events via PubSub. Additionally, component previews now support iframe rendering using srcdoc for standard components and dedicated iframe pages for live components, improving isolation and theme application.

_lib/phoenix\storybook/live/story · high confidence

The JavaScript entry point has been renamed from app.js to phoenix\storybook.js (with a separate iframe variant), and all internal hooks are now namespaced under PhoenixStorybook.\ to prevent silent overrides by host applications. This refactor introduces a functional search modal with keyboard navigation (Tab, Enter, Arrow keys), a new mobile sidebar drawer with slide-in animations, and a robust dark mode system that respects system preferences and persists user selection. Additionally, anchor links within stories are now supported, and a warning is emitted if users attempt to override reserved hooks.

assets/js · high confidence

The rendering logic in lib/phoenix\_storybook/rendering has been restructured into distinct modules to improve separation of concerns. ComponentRenderer now handles the generation and evaluation of HEEx templates for story variations, while CodeRenderer is a new module responsible for syntax-highlighting component source code using the Makeup library. MarkdownRenderer has been updated to use the MDEx library for parsing and delegates code block highlighting to CodeRenderer. RenderingContext and RenderingVariation provide the structured data required by these renderers to process story variations and their attributes.

_lib/phoenix\storybook/rendering · high confidence

The helper modules in lib/phoenix\_storybook/helpers have been reorganized and enhanced. AssetHelpers now computes MD5 hashes for JS and CSS assets at runtime (using persistent\_term caching and mtime/size validation) to ensure correct cache-busting when assets are rebuilt during development. ExampleHelpers now strips storybook-specific functions (like doc, container, extra\_sources) and rewrites use PhoenixStorybook.Story to use Phoenix.LiveView when displaying source code. NavigationHelpers sorts URL query parameters to ensure deterministic paths and fix flaky tests. TemplateHelpers now uses psb- prefixed selectors for variations and groups. ThemeHelpers now accepts both binary and atom values for the data\_attribute theme strategy. ValidationHelpers now restricts local icons to 2 or 3 element tuples.

_lib/phoenix\storybook/helpers · high confidence

The \PhxLiveStorybook.LayoutView\, \PhxLiveStorybook.Router\, and \PhxLiveStorybook.Helpers\ modules have been removed. This eliminates the previous mechanism for embedding the storybook via a dedicated router macro and layout view, as well as the helper functions used to generate storybook paths. Users relying on these specific internal components for integration or path generation will need to adapt to the new routing and asset serving approach introduced in this release.

_lib/phx\_live\storybook · high confidence

The pre-built CSS file at dist/css/app.css has been deleted. This file contained the compiled Tailwind CSS v3.1.6 output, including global resets and base styles. Its removal indicates a shift in how styles are served or generated, likely moving towards on-demand compilation or a different build pipeline, rather than serving a static, pre-compiled stylesheet.

dist/css · high confidence

The application's configuration has been reorganized into environment-specific files (dev, prod, test) with a central config.exs. This change introduces a debug callback via PhoenixStorybook.Dbg for enhanced debugging capabilities and sets the logger level to :info in the test environment. Additionally, the JSON library is explicitly configured to use Jason.

config · high confidence

The \\_sidebar.html.heex\ and \storybook.html.heex\ template files have been deleted from the \lib/phx\_live\_storybook/templates/layout\ directory. This removes the previous static sidebar navigation and the main HTML layout structure that included the sidebar rendering, socket connection setup, and main container divs, indicating a shift in how the Storybook UI is rendered (likely moving to a LiveComponent-based approach as suggested by commit messages).

_lib/phx\_live\storybook/templates · high confidence

The Storybook interface has been renamed to Phoenix Storybook, replacing the previous app.css with a dedicated phoenix\_storybook.css that utilizes Tailwind 4's new configuration syntax and a psb prefix. This change introduces a comprehensive theming system with semantic tokens, enabling full dark mode support and consistent styling across the sidebar, components, and documentation pages.

assets/css · high confidence

The generator templates for Phoenix Storybook have been updated to align with Phoenix 1.8 core components. This includes a new index file that organizes components (button, flash, header, icon, input, list, table) with specific FontAwesome icons, and revised story templates for each component. Key changes include fixing the flash component to correctly reveal hidden messages by removing the hidden attribute on trigger, updating the input component to support various types (text, select, checkbox, textarea, and dynamic types like number, email, password, etc.), and enhancing the table component with examples for function-based row items and action slots. The templates now use the \psb\ prefix for Storybook-specific attributes and ensure proper EEX escaping.

_priv/templates/phx.gen.storybook/core\components · high confidence

Added Storybook test fixtures for \let\ slot bindings; Added component fixtures for testing; Added comprehensive test coverage for Phoenix Storybook live views; Added stub implementations for story types to support testing; Added test fixtures for .index.exs validation; Added test fixtures for Storybook example stories; Added test fixtures for Storybook folder and component stories; Added test fixtures for Storybook folder configuration and component variations; Added test fixtures for Storybook story file parsing; Added test fixtures for Storybook tree structure and component variations; Added test fixtures for nested storybook component structures; Added test fixtures for script execution scenarios; Added test suite for storybook content tree and configuration; Added tests for ExsCompiler and Router functionality; Added tests for JS asset serving and asset-not-found handling; Added tests for LayoutView theming and FontAwesome configuration; Added tests for component, code, and markdown rendering; Added tests for guide rendering and syntax highlighting; Added tests for icon components; Added tests for mix dev.storybook and installer tasks; Added tests for storybook helper modules; Added tests for storybook story validation, documentation, and source extraction; Added tests for template rendering edge cases in Phoenix Storybook.

The project has been renamed to Phoenix Storybook and upgraded to version 1.5.0, requiring Elixir 1.15. This release updates the core dependencies to Phoenix 1.8 and Phoenix LiveView 1.2 (supporting \~\> 1.1.21 or \~\> 1.2.0), and switches the Markdown parser from Earmark to Mdex. On the asset side, the build tooling has moved to Tailwind CSS v4.3.3 and esbuild v0.28.2, with the output directory changed from \../dist\ to \../priv/static\ to align with standard Phoenix asset pipelines.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 51 → 51 (+0.2)
• Rubric changed (rubric-2026.09.15 → rubric-2026.10.1) — scores are not directly comparable.

• Code Health 68 → 69 (+1.2)
• Architecture 99 → 92 (-7.0)
• Maturity 55 → 55 (+0.0)
• Readiness 84 → 84 (+0.3)
• Security 81 → 83 (+2.1)
• Accessibility 34 → 34 (+0.0)

• Documentation: no installation or build instructions (README.md)
• Duplicated block (6 lines × 3) (lib/phoenix_storybook/live/story/component_iframe_live.ex)
• Off-boarding risk: anonymized user #1

• Duplicated block (7 lines × 3) (lib/phoenix_storybook/live/story/component_iframe_live.ex)
• High CVE: [GHSA redacted] (assets/package-lock.json)
• Medium CVE: EEF-[CVE redacted] (mix.lock)
• Off-boarding risk: anonymized user #1
• Outdated: lazy_html
• Outdated: mdex
• Projects may be oversized for their cohesion

• 2 commits — 2 feature/other, 0 fixes

• (root) — 1 commit
• assets/package-lock.json — 1 commit

• change: chore(deps): bump phoenix from 1.8.13 to 1.8.14
• change: chore(deps-dev): bump @biomejs/biome from 2.5.13 to 2.5.14 in /assets

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

phenixdigital/phoenix_storybook was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.