Visual bar: meet-or-beat Tailwind UI kits
Status: normative internal product bar. Adopted 2026-09-11.
Audience: package maintainers, design reviewers, showcase authors.
Not for: public marketing copy. Competitor names stay out of README,
PyPI, and brickworkui.com hero claims (POSITIONING.md claim-honesty rules).
This document stamps the visual quality bar brickwork must meet for the workspace default: our Django projects use brickwork so substrate updates propagate; brickwork must also look finished next to the leading Tailwind UI kits. Composition tests, axe gates and catalogue counts are separate evidence. They do not certify this bar.
Companion docs: POSITIONING.md (lead claim and honesty), DESIGN.md (token vocabulary), BRANDING.md (override recipes), INTERFACE-SYSTEM.md (coverage contract, not visual taste).
1. Licence and clean-room (non-negotiable)
Borrow look and idea only. Every shipped change is clean-room markup and
CSS on the --bw-* layer (reaffirming BR-BW-MKT-003 and the standing
Tailwind Plus reference-only ruling).
| Allowed | Forbidden |
|---|---|
| Screenshots, notes, scorecards comparing rendered jobs | Pasting markup, class strings, or structure from a kit |
| "Kit X wins on spacing rhythm; fix brickwork tokens/CSS" | Redistributing kit assets, Figma files, or derivatives in the wheel |
Local Tailwind Plus trees and Forge stills under the umbrella docs/_examples/ as private Idea refs |
Shipping Tailwind Plus code or anything competitive with Tailwind Labs under that licence; redistributing Forge stills outside this gitignored tree |
MIT and similar kits (daisyUI, Flowbite free core, Preline free library, Headless UI, and the others below) are Idea-reference only for the same reason utility markup would bypass brickwork's token, brand and a11y contract. Tailwind Plus remains reference-only even where we already own copies; new purchases being closed does not relax the licence line.
2. Frozen kit panel (independent shortlist, 2026-09-11)
Do not expand this panel mid-cycle. Optional secondary Idea refs (FlyonUI, HyperUI, Meraki UI, Mamba UI, Tailwind Starter Kit, and the local Forge stills below) stay off the scorecard unless a miss has no panel analogue.
| Kit | Role as bar | What we borrow as ideas | What we do not take |
|---|---|---|---|
| shadcn/ui | Best for React/Next product UI taste: Tailwind-native, copy-paste ownership, strong a11y | Semantic token clarity, option grammar, compositional taste, a11y as default | React ownership model as our upgrade story (we pin and upgrade shells/components); their markup |
| daisyUI | Best free all-framework option: CSS plugin, themes, zero JS, strong for MVPs | Theme density, state coverage, "looks done" with little setup, no-JS expectation | Plugin/utility coupling that bypasses --bw-* |
| Flowbite | Best buyable full kit now: free core + Pro blocks/templates; multi-framework + Figma | Pattern inventory of a complete kit; block/template breadth as a coverage ambition | Markup, JS plugins, multi-framework bindings as brickwork's shape |
| Preline UI | HTML-first sites and dashboards; large free library + Pro blocks | Closest stack cousin: section and dashboard compositions, HTML-first interactions | Class names and script idioms as copy |
| Tailgrids | React blocks + Figma design system; solid Tailwind Plus alternative | Marketing and app block variety; how a design system is packaged for buyers | React/Figma artefacts into the package |
| Tailkit | Cheapest paid snippets (HTML/React/Vue); good for indies | Practical "indie completeness" checklist: what a paid snippet kit is expected to cover | Snippet-dump delivery; unpaid redistribution of their snippets |
| Headless UI | Accessible unstyled primitives (React/Vue) | Behaviour and a11y contracts for overlays, menus, disclosure, focus | Unstyled-only posture (brickwork owns chrome and tokens) |
| Tailwind Plus | Quality ceiling where we already own the set; new purchases closed | Hierarchy, section rhythm, header/footer/flyout craft under docs/_examples/ |
Any code or derivative in shipped templates or CSS |
Review priority within a cycle
- Craft and HTML-first: Tailwind Plus, Preline UI
- Product UI and theme density: shadcn/ui, daisyUI
- Coverage gaps the first four expose: Flowbite, Tailgrids, Tailkit
- Behaviour / a11y only: Headless UI, where the miss is interaction, not paint
Secondary Idea-ref: Forge UI kit stills (local)
Adopted 2026-09-11. Not a frozen-panel member. Local stills only under
the umbrella gitignored path docs/_examples/forge-ui-kit-site/ (same
privacy class as Tailwind Plus trees). Index README in that folder.
Clean-room: look and idea only; never markup, class strings, or structure.
Competitor / kit names stay out of public marketing copy.
Use these stills to sharpen what "finished" means on brickwork surfaces. Rendered scorecards still cite Priority 1 and 2 panel kits as leaders; Forge may appear in a single row as an Idea-ref when it clarifies a miss better than a panel analogue.
| Still | Primary surface | Review weight |
|---|---|---|
07-dashboard.png |
S4 app dashboard | Highest |
08-forms.png |
S3 app form | Highest |
09-settings.png |
S2 detail / settings (nav craft aids S1) | Highest |
01-home.png |
S5 marketing landing | High |
04-blocks.png |
S6 marketing pricing | High |
05-templates.png |
S4 via nested dashboard preview | Medium to high |
06-themes.png |
Theme density (daisyUI lane) | Medium |
02-primitives.png |
S7 docs density only | Low |
03-components.png |
Kit catalogue chrome | Ignore for scorecard |
Clean-room borrow ideas (not markup): metric card and sparkline rhythm; activity list plus table split; form error, help and character-counter grammar; danger zone as a distinct surface; settings nested nav; light borders over heavy shadows; accents reserved for status.
3. Surfaces under test
Fixed package-owned jobs. Prefer shipped examples under
src/brickwork/examples/ rendered with package-only CSS, then the same
surfaces with one intentional brand override. Showcase brand CSS alone
does not prove package defaults.
| ID | Surface | Primary example / shell |
|---|---|---|
| S1 | App list | examples/app/list.html + app shell |
| S2 | App detail | examples/app/detail.html |
| S3 | App form | examples/app/form.html |
| S4 | App dashboard | examples/app/dashboard.html |
| S5 | Marketing landing | examples/marketing/landing.html + marketing shell |
| S6 | Marketing pricing | examples/marketing/pricing.html |
| S7 | Docs article | examples/docs/article.html + docs shell |
| S8 | Dense ops | examples/ops/dense-list.html + app shell |
Fixtures must be credible for the job (populated filters, realistic fields, working assets). Thin or broken fixtures are site defects first; do not score them as package visual wins or losses until corrected.
4. Scorecard axes
Each surface × theme (light, dark) × viewport (desktop ~1440px, phone ~375px). Score pass / fail / not applicable. Failures cite the kit that sets the bar and a one-line borrow idea.
| Axis | Pass means |
|---|---|
| Hierarchy | One clear focal point; heading scale is deliberate, not near-body |
| Typography | Type roles read as a system; measure and weight support the job |
| Spacing rhythm | Consistent vertical cadence; no large accidental voids or cramped bands |
| Surface differentiation | Content roles are distinguishable without relying on endless identical bordered boxes |
| Density | Appropriate for the family (marketing air vs ops density); not sparse by accident |
| States | Loading, empty and error are designed where the component promises them |
| Navigation / mobile chrome | Desktop nav and a usable mobile pattern; no verbatim consumer rebuild of shell internals |
| Forms | Labels, controls, help and errors align; primary actions are obvious |
| Section cadence (marketing) | Sections feel sequenced, not stacked templates |
| Brandability | The same composition still holds after a seven-token brand override |
Out of scope for this scorecard: axe CI green alone, inventory counts,
kiln or demo identity preference, whether every INTERFACE-SYSTEM.md
archetype exists.
5. Empty scorecard (fill on a rendered pass)
Record package version, date, reviewer, and whether the render used package-default CSS only or also a named brand pack.
| Surface | Kit that led | Axes failed | Borrow idea (clean-room) | Package follow-up |
|---|---|---|---|---|
| S1 App list | ||||
| S2 App detail | ||||
| S3 App form | ||||
| S4 App dashboard | ||||
| S5 Marketing landing | ||||
| S6 Marketing pricing | ||||
| S7 Docs article | ||||
| S8 Dense ops |
Store completed scorecards under docs/audits/ with a dated filename, e.g.
docs/audits/2026-09-11-visual-bar-scorecard.md. Link the latest pass from
this section when one exists.
Latest completed pass:
audits/2026-09-12-visual-bar-signoff-pass.md
(Phase 5 independent re-sign after remediation; tip e79f828). Prior notes:
audits/2026-09-12-visual-bar-signoff.md
(FAIL),
audits/2026-09-11-visual-bar-scorecard.md
(Phase 1 package-only),
audits/2026-09-12-visual-bar-scorecard-phase3.md
(Phase 3 craft),
audits/2026-09-12-visual-bar-brand-northline.md
(Phase 4.3 Brandability under northline).
Package-default proof gallery (Phase 4.2): npm run visual-bar:fixtures
then npm run visual-bar:capture is the package-default proof gallery for
S1 to S8. It uses package-only CSS (compiled brickwork.css inlined). It does
not apply showcase, kiln, or any product identity. Private stills land
under audits/_stills/ (gitignored PNGs; README only
committed). Not a CI gate.
Brand pack second leg (Phase 4.3 / Beat F.1): npm scripts
visual-bar:fixtures:<brand> then visual-bar:capture:<brand> reuse the same
S1 to S8 map with the fictional skeletons under
docs/examples/brand-pack/ (northline, harbour, folio). Stills land
under _stills/<date>-<brand>/. Density: set VISUAL_BAR_DENSITY=compact
(default comfortable) on both fixtures and capture; fixture dirs and
default stills folders append -compact when non-default. Surface subset:
VISUAL_BAR_SURFACES=s1,s3,s5 (comma-separated IDs; default all S1 to S8).
See audits/_stills/README.md for the recipe.
6. Done criteria
This bar is met for a release train when:
- An independent rendered review has filled the scorecard for S1 to S8 at both themes and both viewports against at least the priority-1 and priority-2 kits.
- Every fail has a package issue or an explicit "won't fix / consumer-owned" reason.
- Package-default CSS (no showcase brand) clears the axes that failed for substrate reasons.
- Public copy still does not claim a house aesthetic or name competitors as
brickwork's identity (
POSITIONING.mdsections 3, 9, 10).
Section 6 status: met for tip e79f828 by the dated pass audit linked
above. Re-run the independent rendered review when a MINOR changes default
chrome on S1 to S8; Phase 4 stills alone are not a substitute for that review.
Workspace rule (separate from this file): our Django projects that ship hand-built template UI standardise on brickwork so pins receive substrate updates. This bar is what makes that standard visually defensible.
7. Revision
- Panel freeze: change the kit table only in a dated amendment with owner agreement.
- Surfaces: add only when a new family becomes part of the workspace default proof set.
- Secondary kits: may appear in a single scorecard row as Idea refs; they do not join the frozen panel without an amendment.
- 2026-09-11: stamped Forge UI kit local stills as a secondary Idea-ref
(
docs/_examples/forge-ui-kit-site/under the umbrella); panel unchanged.