⭐ Found this useful? Install from Packagist · Give it a star on GitHub so more developers can find it.
Canonical admin UI kit for Nowo Symfony bundles and host apps: Twig macros, semantic nowo-ui-* CSS, pagination/tabs/modals/toasts/confirm/loader, cards/filters, shell chrome (aside / nested nav / burger / avatar / user menu / footer / width toggle), theme/locale/kebab helpers, Thinking Orbs (local canvas, no CDN), and multi-framework class helpers (bootstrap5, tailwind, foundation, custom, …) per REQ-UI-001.
Compatible with Symfony 7.4+ and 8.x (PHP 8.2+; Symfony 8 requires PHP 8.4+).
This bundle is FrankenPHP worker mode friendly (including when the kernel is not reset between requests). See docs/FRANKENPHP-WORKER-AUDIT.md.
List scaffold — host theme (tokens + class map + partial override) |
Dashboard scaffold — KPI tiles and cards grid |
Same list, UiKit default theme — row delete confirm dialog |
- What this is / is not
- Features
- Installation
- Quick start
- Page contract (UiKit 2.0)
- Demos
- Documentation
- Tests and coverage
- License
- Contributing
| Is | Is not |
|---|---|
| Buttons, toolbars, tables, lists, pagination, tabs, flashes/toasts, empty states, modal/confirm, cards/filters, icons, aside (nested) / burger / avatar / user menu / footer, theme/locale/kebab/width, Thinking Orbs | DashboardMenu / BreadcrumbKit navigation chrome |
Shared nowo-ui-* look-and-feel |
Domain CRUD pages / manage routes |
| Multi-framework class macros | Form widget themes (use FormKit) |
- Twig macros (
@NowoUiKitBundle/macros/ui.html.twig) with optional per-callframeworkoverride - Semantic stylesheet
css/nowo-ui.css(asset packagenowo_ui_kit), including dark[data-theme="dark"]tokens - Complete
--nowo-ui-*theming tokens (1.13): every colour, radius, font, focus ring, overlay and shadow in kit output reads a token — no hard-coded Tailwind palette / Bootstrap colour utilities; a host theme is a short:rootblock (docs/THEMING.md); opt-in.nowo-ui-bs-tokensbridge for Bootstrap 5.3 stacks - Optional appearance SPI (1.16): presets (ocean, slate, sandstone, midnight, obsidian, aurora, ember + host presets), corner / border styles, a
--nowo-ui-*token emitter with host aliases,nowo_ui_appearance_style()(CSP nonce), host storage behindAppearanceProviderInterface, optionalAppearanceTypeform — see docs/THEMING.md. 2.40: logo slots (AppearanceLogos) in the shell, auth, guest and error pages, opt-innowo_ui_appearance_head(), and an optionalnowo-tech/brand-contractsBrandProviderInterfacethat drives name, colours and logos when no provider is set;vendor/bin/nowo-ui-token-lint— see docs/THEMING.md - Host chrome (1.17, opt-in): responsive tables (scroll ↔ responsive, row detail dialog, host-owned persistence), foldable filter cards, card corner tabs, disclosure chevrons, page-edge tab +
nowo_ui_route_link()route map, unified thin scrollbars (CSS + SCSS mixin), optional morphicons module — see docs/USAGE.md - Locale tabs (2.5):
locale_tabspartial — one panel per locale for per-locale form fields, WAI-ARIA tabs (keyboard, RTL, error / required / default markers with screen-reader text), stacked fieldsets without JavaScript, browser validation opens the hidden panel,nowo-ui:tabs:changefor editors, Live Component safe — see docs/USAGE.md - Kit templates (2.6): branded HTTP error pages for every status code (
@NowoUiKit/error/status.html.twig: illustration, retry / back links, 429Retry-After, 5xx self-reload, skip link, CSP nonce), the Stimulusconfirm_dialogwrapper, the signed-in app shell (open / close halves, cookie-rendered aside, morph burger) and a compact pagination with an auto-submitting per-page select — see docs/USAGE.md - Detail pages (2.21, opt-in): status badge next to the title (
PageStatus), split header actions (square icon buttons, one primary button, a square "more" menu with destructive actions last and their confirm dialogs outside the popover —header_actionspartial), a key figures row (Stat,stat_row) and a compact details grid (DetailSectionlayout: 'facts'); font preload tags (font_preloadconfig,nowo_ui_font_preload()) — see docs/USAGE.md - Compact header (2.27, opt-in): the breadcrumb and the page actions in the top bar — shell slot
header_context, partialsheader_context,header_crumbs(one-line trail, "…" disclosure, phone "‹" up link, opt-innowo-ui-header-crumbs.js) andpage_actions, acompactpage-header presentation per request (_nowo_ui_header_presentation,nowo_ui_kit.header); Twignowo_ui_header_presentation(),nowo_ui_breadcrumb_kit_trail(),nowo_ui_header_crumbs()and the globalnowo_ui_header— see docs/USAGE.md - Full-height sidebar layout (2.32, opt-in):
nowo_ui_kit.shell.sidebar_layout: full-height(per request:_nowo_ui_sidebar_layout/ thesidebar_layoutoption) — the aside from the top edge with the burger and the brand in its head, header and footer at its right edge; the brand from config (nowo_ui_kit.shell.brand) or options, no template override; opt-in hover-expanded rail (hover_expand) — see docs/USAGE.md - Inset sidebar style (2.52, opt-in):
nowo_ui_kit.shell.sidebar_style: inset(per request / per user:_nowo_ui_sidebar_style/ thesidebar_styleoption) — GitLab-like shell: header, aside and footer on one surface without borders, the content in an inset rounded panel (--nowo-ui-shell-inset-*tokens, light and dark); phones unchanged — see docs/USAGE.md - Shell focus mode (2.55, opt-in):
nowo_ui_kit.theme.focus_mode— afocus_mode_togglepartial ([data-nowo-ui-focus-mode]) hides the shell regions (sidebar, top bar, footer, side panels, edge tabs, a host's dock;keeplist for a search field, a timer chip, a one-line breadcrumb) so the work area goes full width, with an optional second step into the browser fullscreen;F/ Escape, remembered per area, live-region announcements,inertregions — see docs/USAGE.md - Remote form dialog (2.28): a form page opened in a native
<dialog>and posted back withfetch(422re-rendered,204+X-Nowo-Redirectfollowed, same-origin only) — IIFE mode ofnowo-ui-dialog.js, Stimulus peerremote-form-dialog, partialremote_form_dialog, server helperRemoteDialogResponder— see docs/USAGE.md - Overlay registry (2.28):
window.NowoUiOverlaykeeps the shellinertunder drawers, markshtml[data-nowo-overlay]and dispatchesnowo:overlay-open/nowo:overlay-close(ChatKit's dock listens); the layer scale (--nowo-ui-z-*) is public API — see docs/USAGE.md - TypeScript → IIFEs: modal, shell, toast, confirm, page-loader, theme, theme-boot, orb, clipboard, tabs, release, open-modal
- Pre-paint theme boot (1.15):
_theme_boot.html.twiginlines a blocking script (CSP nonce) that applies theme / density / motion / font scale / contrast from<html>attributes before first paint, sharing storage keys with the theme toggle - Opt-in three-mode sidebar (1.15): expanded / icons-only rail / hidden, cookie + localStorage sync with configurable keys (
data-nowo-ui-sidebar-rail) - Deep link "open modal on load" (
?new=1):_open_modal_on_load.html.twigJSON island +nowo-ui-open-modal.js(CSP-safe, no inline JS) - Opt-in filter bar / data table chrome:
.nowo-ui-filter-bar(38px / compact 34px controls, actions on one row) +_filter_actions.html.twig(icon / icon-only actions since 1.15),table.nowo-ui-data-table - Page loader: veil (spinner / orb) or minimal indicators (top bar, looping bar, corner spinner, dots, glow, corner logo); cross-page fades via
_page_transition.html.twig(View Transitions, no JS) - Optional Stimulus peers under
src/Resources/assets/stimulus-peers/(see docs/STIMULUS.md) —confirm-submit(form submit or single button click,blockedvalue),confirm-dialog,tabs,toast-stack,clipboard-copy,page-loader,release-status,auto-refresh,temporary-reveal,collapse-panel,datatable(optional DataTables dependency),responsive-table,filters-collapse,disclosure-icon(1.17),listing-customizer,product-tour(2.13, optional driver.js),multi-select(2.14: Tom Select chips forChoiceTypemultiplefilters via thenowo_ui_multi_selectoption, optionaltom-select, skincss/nowo-ui-multi-select.css),date-range(2.15: one labelled from / to filter fieldDateRangeTypewith a range calendar, optionalcally; two native date inputs without JavaScript),table-sort(2.20: client-side sortable headers ofView\Table/ListPageclientSort; server-side ones useListing\SortRequest) - Optional release check (off by default): installed-version button + lazy GitHub “newer release?” dialog (
release_checkconfig,_release_version.html.twig,nowo-ui-release.js) — see docs/CONFIGURATION.md - Thinking Orbs:
_thinking_orb+nowo-ui-orb.js; page loadervisual: orb|spinner(THIRD_PARTY.md) - Config:
css_framework,icon_set,row_actions_display,base_stylesheet,appearance,route_links,font_preload; i18n domainNowoUiKitBundle(en,es,it,fr,pt,de,nl) - Twig namespace overrides under
templates/bundles/NowoUiKitBundle/ - Adoption + Stimulus contracts: docs/ADOPTION.md, docs/STIMULUS.md
composer require nowo-tech/ui-kit-bundle
php bin/console assets:installWith Flex, the recipe creates config/packages/nowo_ui_kit.yaml. See docs/INSTALLATION.md and docs/RECIPE.md.
# config/packages/nowo_ui_kit.yaml
nowo_ui_kit:
css_framework: bootstrap5 # or: tailwind | foundation | custom
icon_set: bootstrap-icons
row_actions_display: icon # or: text | icon_text
# base_stylesheet: true # 2.51: UiKit's default theme (body font, page gutters, masthead) for apps with no
# # CSS framework and no theme file — docs/THEMING.md#the-default-theme-251
# panel_path_rewrites: # optional (1.9.0+): rewrite kit routes + 301 legacy URLs
# '/admin/blog': '/panel/blog'
# release_check: # optional (1.10.0+): footer version + GitHub release dialog
# enabled: true
# github_repo: 'acme/my-app'
# current_version: '%app.version%'{% import '@NowoUiKitBundle/macros/ui.html.twig' as ui %}
<link rel="stylesheet" href="{{ asset('css/nowo-ui.css', 'nowo_ui_kit') }}">
<button type="button" class="{{ ui.btn('primary') }}">Save</button>See docs/USAGE.md and docs/CONFIGURATION.md.
REQ-UI-003 — UiKit owns the page shell of every Nowo UI bundle: canonical layouts, one scaffold per view type
(@NowoUiKit/page/{list,show,form,settings,dashboard,confirm,wizard,auth}.html.twig), immutable view models
(Nowo\UiKitBundle\View\*) and one global theme (nowo_ui_kit.theme: slot classes, attributes, partial overrides,
--nowo-ui-* tokens, per-bundle exceptions). A host themes each view type once; bundles fill data blocks only.
Screenshots of every scaffold (host theme and default theme): docs/PAGE_CONTRACT.md.
- Page contract — concepts, layouts, scaffolds and data blocks, view models, bundle and host examples
- Theme slots — slot vocabulary with defaults per
css_framework, partials, tokens, per-bundle exceptions - Migrating bundles — recipe for UI bundles (view models, scaffolds, bridges, config aliases, contract test,
docs/TEMPLATES.md) Nowo\UiKitBundle\Test\PageContractTestCase— shared contract test for UI bundles (needsphpunit/phpunitin the bundle'srequire-dev)
FrankenPHP demos (Caddy + PHP). Runtime mode: FRANKENPHP_MODE (worker default; classic for per-request PHP). See docs/DEMO-FRANKENPHP.md.
| Demo | Port | Notes |
|---|---|---|
| demo/symfony8 | 8092 | Bootstrap 5 kitchen sink; page contract host-theme demo at /page-contract |
| demo/symfony8-tailwind | 8093 | Tailwind kitchen sink |
make -C demo up-symfony8
# open http://localhost:8092/- Installation
- Configuration
- Usage
- Contributing
- Code of Conduct
- Changelog
- Upgrading
- Release
- Security
- Engram
- Spec-driven development
- GitHub Spec Kit
- Roadmap
- PSR evaluation (REQ-CS-007)
- Theming (
--nowo-ui-*tokens) - Page contract (REQ-UI-003)
- Theme slots
- Migrating bundles to the page contract
- Row actions (canonical kinds)
- Adoption (Beacon + bundles)
- Stimulus / data contracts
- Overriding bundle templates
- Third-party notices
- Flex recipe
- FrankenPHP demos
- FrankenPHP worker audit
- Coverage
- GitHub Actions CI
| Version | Status |
|---|---|
| 2.x | Current (main) |
| 1.x | Maintenance (1.x branch, fixes only) |
Security support: .github/SECURITY.md.
Unit tests (tests/Unit) and kernel integration tests (tests/Integration) run with PHPUnit; the TypeScript runtimes
and Stimulus peers run with Vitest (happy-dom). Figures below are the CI Code Coverage and Vite / TypeScript jobs.
| Suite | Coverage |
|---|---|
| PHP (PHPUnit) | 100% lines (3253/3253; CI fails under 100%) |
| TypeScript (Vitest) | 100% lines (2810/2810), 95.76% branches (gated set, see COVERAGE.md; thresholds 90% lines / 85% branches) |
| Python | N/A |
composer install
make test
make test-coverage
make test-ts
pnpm install && pnpm run buildSee docs/COVERAGE.md.
MIT — see LICENSE.
See docs/CONTRIBUTING.md. Install hooks with make setup-hooks (REQ-GIT-001).



