README

⭐ 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.

What this is / is not
Features
Installation
Quick start
Demos
Documentation
Tests and coverage
License
Contributing

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
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.twig inlines 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.twig JSON 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, blocked value), confirm-dialog, tabs, toast-stack, clipboard-copy, page-loader, release-status, auto-refresh, temporary-reveal, collapse-panel, datatable (optional DataTables dependency)
Optional release check (off by default): installed-version button + lazy GitHub “newer release?” dialog (release_check config, _release_version.html.twig, nowo-ui-release.js) — see docs/CONFIGURATION.md
Thinking Orbs: _thinking_orb + nowo-ui-orb.js; page loader visual: orb|spinner (THIRD_PARTY.md)
Config: css_framework, icon_set, row_actions_display, appearance; i18n domain NowoUiKitBundle (en, es, it, fr, pt, de, nl)
Twig namespace overrides under templates/bundles/NowoUiKitBundle/
Adoption + Stimulus contracts: docs/ADOPTION.md, docs/STIMULUS.md

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.

Demos

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
demo/symfony8-tailwind	8093	Tailwind kitchen sink

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).

nowo-tech / ui-kit-bundle

Package info

Security

Statistics