Nowo UiKit Bundle
⭐ 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.
Table of contents
What this is / is not
| 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) |
Features
- Twig macros (
@NowoUiKitBundle/macros/ui.html.twig) with optional per-call framework override
- Semantic stylesheet
css/nowo-ui.css (asset package nowo_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 :root block (docs/THEMING.md); opt-in .nowo-ui-bs-tokens bridge 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 behind AppearanceProviderInterface, optional AppearanceType form — 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_tabs partial — 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:change for 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, 429 Retry-After, 5xx self-reload, skip link, CSP nonce), the Stimulus confirm_dialog wrapper, 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
Installation
composer require nowo-tech/ui-kit-bundle
php bin/console assets:install
With Flex, the recipe creates config/packages/nowo_ui_kit.yaml. See docs/INSTALLATION.md and docs/RECIPE.md.
Quick start
# 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
# 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.
Page contract (UiKit 2.0)
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 (needs phpunit/phpunit in the bundle's require-dev)
Demos
FrankenPHP demos (Caddy + PHP). Runtime mode: FRANKENPHP_MODE (worker default; classic for per-request PHP). See docs/DEMO-FRANKENPHP.md.
make -C demo up-symfony8
# open http://localhost:8092/
Documentation
Developer-facing docs are English only (Contributing — Language policy).
Tests and coverage
| Suite | Coverage |
|---|
| PHP (PHPUnit) | 100% lines (fail under 99% in CI) |
| TypeScript (Vitest) | ≥90% lines (Vitest thresholds) |
| Python | N/A |
composer install
make test
make test-coverage
make test-ts
pnpm install && pnpm run build
See docs/COVERAGE.md.
License
MIT — see LICENSE.
Contributing
See docs/CONTRIBUTING.md. Install hooks with make setup-hooks (REQ-GIT-001).
