UI Patterns Library Admin Theme
This module enhances the UI Patterns component library by rendering its documentation within your administration theme while displaying component previews in isolated iframes. This ensures that documentation elements are styled correctly by your admin theme, and each component preview accurately reflects its appearance in the front-end theme without interference. The previews are dynamically sized and stripped down to show only the component itself.
UI Patterns ships a components library at /admin/appearance/ui/components that lists every SDC component on your site together with its props, slots and stories. Because the previews have to render with your front-end theme's CSS, the whole page is served in the front-end theme — so the documentation around them loses the administration theme, and the previews themselves inherit whatever your front-end theme does to headings, tables and links.
This module separates the two. The library pages render in your administration theme, and every story is previewed inside its own iframe that loads the front-end theme on its own. Documentation looks like the rest of your admin interface; components render exactly as they do on the site, in a real document of their own, with nothing from the admin theme leaking in.
Features
Enabling the module changes how the existing library pages are rendered. There is nothing new to place, configure or author — your existing *.story.yml files are used unchanged.
- Library pages in the administration theme. The overview, per-provider and single-component pages become admin routes, so the props tables and metadata are styled by Gin, Claro or whichever admin theme you use.
- Every story in its own document. Each story — and each variant of a story — is rendered by a separate route in the front-end theme and embedded in an iframe. Components get their real stylesheets, import maps, JavaScript and cascade, with no admin CSS in scope.
- Frames sized to their content. Previews are measured and resized as they load, as custom elements upgrade, and on any later reflow, so there are no fixed heights, no inner scrollbars, and no clipped stories.
- A genuinely bare preview shell. Inside the frame there is no admin toolbar, no page title, no status messages, no regions or blocks, and no off-canvas wrapper — only your component.
- No scrollbar in the preview. Overflow is suppressed inside each frame, so a stray pixel of off-screen markup cannot introduce a scrollbar that narrows the viewport your component lays itself out against.
- Previews that match the surrounding page. When Gin is the administration theme, each preview takes Gin's layer colour so stories sit on the same surface as the documentation around them, following Gin's light/dark toggle live. With any other admin theme this step is simply skipped.
Use it if you build a component library with UI Patterns and want the library to double as a browsable reference for the whole team: designers and content editors reading component documentation in familiar admin chrome, while front-end developers see each component rendered exactly as the site renders it. It is also useful whenever your front-end theme's global styles make the stock library page hard to read, or whenever your components depend on front-end assets — import maps, web components, custom properties — that the administration theme does not load.
Post-Installation
There is no configuration. Install and enable the module, then visit Appearance → UI libraries → Components library (/admin/appearance/ui/components). The pages you already know will be rendered in the new way.
Two permissions are involved, both from Drupal core and UI Patterns Library rather than this module:
- Access components page — required to view the library, and to view an individual story preview.
- View the administration theme — a user without it still sees the library, rendered in the front-end theme as before. The story previews are unaffected either way.
Story previews are served from /ui-patterns/component-story/{provider}/{machine_name}/{story_id}/{variant}. These are ordinary pages: you can open one directly to debug a single component in isolation, or link to it from design documentation. The library_wrapper property of a story is honoured, so a story can still bring its own markup around the component.
Additional Requirements
- Drupal 10 or 11.
- UI Patterns 2.x, with its UI Patterns Library submodule enabled. This module is an enhancement to that submodule and does nothing without it.
No external libraries, build step or Node.js tooling is required.
Recommended modules/libraries
- Gin — not required, but the preview background integration is written against Gin's design tokens, so stories blend into the page and follow Gin's dark mode. Every other feature works identically under Claro or any other administration theme.
Similar projects
This module is not an alternative to UI Patterns Library — it extends it, and the two are always used together.
If you want a full component-explorer experience with controls for editing props live, look at the Storybook-based options such as Component Libraries: Server, which renders Drupal components into an external Storybook instance. Those give you more, at the cost of a Node.js toolchain and a second application to run and keep in sync. This module deliberately stays inside Drupal: no build step, no separate server, and stories authored the same way they already are.
How it works
Understanding this helps when debugging a preview that looks wrong.
The library routes are marked as admin routes, so the documentation renders in the administration theme. Each story is then rendered by a separate route, /ui-patterns/component-story/{provider}/{machine_name}/{story_id}/{variant}, which is deliberately not an admin route — that is what gives the component the front-end theme, its import maps and its assets. The library templates embed one iframe per story and per variant.
Inside the frame the page is stripped to the component alone: no toolbar, no page title, no status messages, no regions or blocks, and no off-canvas wrapper. Overflow is suppressed so that a stray pixel of off-screen markup cannot introduce a scrollbar, which would narrow the viewport the component lays itself out against.
Frames carry no fixed height. A small script measures each loaded document and keeps the frame in sync — on load, as custom elements upgrade, on any later reflow, and when a backgrounded tab is focused again.
Troubleshooting
A preview is blank or much shorter than expected. The frame is sized to its content, so a zero-height preview usually means the story itself renders nothing — check the story's props and slots by opening its /ui-patterns/component-story/… URL directly.
A preview is styled by the administration theme. The story route must not be an admin route. Anything that marks routes under a path as admin routes, or a theme negotiator that ignores the flag, will pull the frame into the admin theme.
Previews do not pick up the front-end theme's assets. The frame renders with the default theme, not the theme of any particular page. Assets attached per-route or per-page on the front end will not be present.