This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
- Flowbite Blazor is a Blazor component library that ports Flowbite React to ASP.NET Blazor 8/9 on top of Tailwind CSS v4.
- Current status: beta (
v0.2.x-beta); APIs are stabilizing but may change. - Work from the
developbranch for new changes and pull requests.
src/Flowbite/— core component library (multi-targetsnet8.0;net9.0; code must compile for both).src/Flowbite.ExtendedIcons/— optional icon packs (net8.0).src/DemoApp/— Blazor WebAssembly documentation site (net9.0); mirror every new component with a demo page.src/Flowbite.Tests/— bUnit unit tests and Playwright integration tests (net9.0).- Place shared docs under
docs/, automation inscripts/, and ship-ready static assets under each project’swwwroot/. - Each shipped project has its own
CHANGELOG.md(src/Flowbite/,src/Flowbite.ExtendedIcons/,src/DemoApp/); the rootCHANGELOG.mdis only an index. Update the relevant one before committing a feature.
Use build.py for all build, run, and test operations.
Prerequisites: .NET 9 SDK, Python with psutil (pip install psutil), and npm ci at the repo root (Tailwind resolves @plugin "flowbite/plugin" from the root node_modules).
python build.py/python build.py build— Run Tailwind for both projects, then buildFlowbiteBlazor.slnpython build.py watch— Run DemoApp with hot reload (foreground, Ctrl+C to stop)python build.py run— Run DemoApp in foregroundpython build.py start— Auto-builds, then starts DemoApp in background (http://localhost:5290)python build.py stop— Stop background DemoApppython build.py status— Check if DemoApp is running
Key Behaviors:
buildauto-stops any running DemoApp (prevents file lock errors)startauto-builds before launching (always runs latest code)- The Tailwind standalone CLI is auto-downloaded to
tools/on first run. The csproj Tailwind targets fail if it is missing, so runpython build.pyonce before usingdotnet builddirectly.
python build.py pack— Create NuGet packages innuget-local/python build.py publish— Pack NuGet + publish DemoApp todist/
python build.py test— Run unit tests (excludesCategory=Integration)python build.py test <filter>— Run tests matching adotnet testfilter, e.g. a class (python build.py test DebouncerTests) or a single test (python build.py test "FullyQualifiedName~DebouncerTests.MethodName"). A custom filter replaces the default integration exclusion.python build.py test-integration— Run Playwright smoke tests (auto-starts/stops DemoApp)python build.py test-publish— Release pack + publish of DemoApp; catches pre-rendering errors on every pagepython build.py test-all— Unit, then publish, then integration; fails fast
Tests live in src/Flowbite.Tests/ — read src/Flowbite.Tests/CLAUDE.md for test patterns (FlowbiteTestContext base class, JSInterop mocking, Playwright fixture). Integration tests need Playwright browsers installed once (see that file).
CI (.github/workflows/ci.yml) runs build + test on .NET 8 and 9, then publish and test-integration.
python build.py log— Show last 50 lines ofdemoapp.logpython build.py log <pattern>— Search log for regex pattern (case-insensitive)python build.py log --tail <n>— Show last n linespython build.py log --level error— Filter by log level (error/warn/info/debug)
- Direct build:
dotnet build FlowbiteBlazor.sln - Direct watch:
dotnet watch --project src/DemoApp/DemoApp.csproj - Manual Tailwind (run from the project directory):
src/Flowbite:../../tools/tailwindcss -i ./wwwroot/flowbite.css -o ./wwwroot/flowbite.min.css --minifysrc/DemoApp:../../tools/tailwindcss -i ./wwwroot/css/app.css -o ./wwwroot/css/app.min.css --minify
- Rebuild the Floating UI bundle:
npm install && npm run buildinsidesrc/Flowbite/(see JavaScript interop below) - Regenerate docs context:
pwsh -File Build-LlmsContext.ps1insidesrc/DemoApp/. This runs automatically on Windows builds only; on macOS/Linux run it manually after editingllms-docs/.
FlowbiteComponentBase— providesClass,Style,AdditionalAttributes(captures unmatched attributes),CombineClasses(), andMergeClasses(). It injectsTwMerge, so any component render requiresAddFlowbite()to have been called.FlowbiteInputBase<TValue>— extends Blazor'sInputBase<TValue>(notFlowbiteComponentBase) for form inputs; subscribes toEditContextvalidation changes so inputs switch to the Failure color automatically.IconBase— SVG icons with aria and stroke control.OffCanvasComponentBase— manages visibility for drawers, modals, and toasts.
- PREFER the
ElementClassfluent builder for component class logic (src/Flowbite/Utilities/ElementClass.cs) - Use
ElementClass.Empty().Add("class").Add("conditional", when: bool)for readable conditional classes - Pass the result to
MergeClasses()for TailwindMerge.NET conflict resolution (later classes win) - Example:
MergeClasses(ElementClass.Empty().Add("px-4").Add("hidden", when: !visible).Add(Class)) - Slots: components with multiple styled inner elements expose a
Slotsparameter (CardSlots,ModalSlots, … insrc/Flowbite/Common/, all deriving fromSlotBase). Add slot classes last in theElementClasschain so user overrides win; seeCard.razor.csfor the reference pattern.
- Two-file pattern:
Component.razorfor markup andComponent.razor.csfor logic. - Enums, context, and options types sit beside their component (e.g.
ModalEnums.cs,ModalContext.cs,ModalOptions.cs). - Built-in icons are in
src/Flowbite/Icons/.
AddFlowbite()inServiceCollectionExtensions.csis the single registration entry point (TailwindMerge, modal/drawer/toast services, floating service, lazy JS services). New services must be added there and get their ownAddFlowbite*method.- Programmatic UI services (
IModalService,IDrawerService,IToastService) pair with host components such asModalHostandToastHost.
- Lazy module services (
ClipboardService,ElementService,FocusManagementService) hold aLazy<Task<IJSObjectReference>>that imports./_content/Flowbite/js/<module>.json first use. Follow this pattern for new JS rather than adding global scripts. FloatingService(dropdown/tooltip/popover positioning) depends onwwwroot/js/floating-ui.bundle.js, a committed Rollup IIFE built fromsrc/Flowbite/js-src/. Editingjs-src/requires rebuilding and committing the bundle; consumers load it via a<script>tag.
- Pages under
src/DemoApp/Pages/Docs/components/. - Sidebar data in
src/DemoApp/Layout/DocLayoutSidebarData.cs. - AI documentation snippets in
src/DemoApp/wwwroot/llms-docs/sections/, concatenated intowwwroot/llms-ctx.md. - Debug builds reference the library projects directly; Release builds consume the packages from
nuget-local/(sopackmust run before a Release publish —publishandtest-publishdo this). - The site is statically pre-rendered at publish time (
BlazorWasmPreRendering.Build). Keep service registration inside the staticConfigureServiceslocal function inProgram.cs, and make sure pages render without a browser (e.g. no missing@bind-Value, no JS calls beforeOnAfterRenderAsync). Runpython build.py test-publishafter adding or changing pages.
- 4-space indentation, file-scoped namespaces, PascalCase public APIs,
_camelCaseprivate fields. - Keep C# logic in
.csfiles via partial classes; parameters are public properties with[Parameter]. - Use
RenderFragment? ChildContentfor slots of markup, and prefer enums for style variations. - Always apply
@keywhen looping components with@foreach. - Use Tailwind utility classes exclusively; ensure dark mode coverage with
dark:variants and accept aClassparameter for custom styling. - Only use icons from
Flowbite.IconsorFlowbite.ExtendedIcons; add missing glyphs internally. - Document all public APIs with XML comments.
- Tailwind v4 is configured CSS-first. The real configuration (
@sourcescan paths,@plugin,@theme) lives insrc/Flowbite/wwwroot/flowbite.cssandsrc/DemoApp/wwwroot/css/app.css. - Each project's
tailwind.config.jsis still loaded via@configsolely to getdarkMode: 'class'with correct specificity. Do not replace it with@custom-variant dark— that emits zero-specificity:where()selectors and breaksdark:overrides (explained in the header offlowbite.css). - New source directories containing Tailwind classes must be added as
@sourcelines in the relevant CSS file or their classes will not be generated. - CRITICAL: Always commit
*.min.css. They are generated by the Tailwind CLI during build; whenever Tailwind classes are added or changed, commit:git add src/Flowbite/wwwroot/flowbite.min.css git add src/DemoApp/wwwroot/css/app.min.css
- It is ULTRA IMPORTANT to adhere to the Flowbite Design Style System as it is mobile first and good looking.
- PREFER to use Flowbite Blazor UI components rather than custom components.
- Developer Rules:
docs/developer_rules.md— coding standards and git workflow - Memory Aid:
docs/memory_aid.md(index) + topic files indocs/memory_aid/— lessons learned & gotchas - PREFER to load and read both files prior to editing any source file
- You MUST EDIT the appropriate file in
docs/memory_aid/after learning a new pattern or gotcha
- Exercise both light and dark themes, keyboard navigation, and key scenarios on the demo pages.
- When fixing bugs, reproduce them in the demo first, then validate the fix there.
- Non‑negotiable: drive every meaningful UI verification through a scripted browser run. Launch the DemoApp, navigate to the affected surface, and capture evidence (screenshots or DOM state) before calling a change "done."
- Tool preference: use the
playwright-cliskill (invoke it via the Skill tool). Fall back to the Playwright MCP server (mcp__playwright__browser_*), then to the built-in browser pane, only if the CLI is unavailable. Checkwhich playwright-clibefore concluding it is missing. - Dependencies: the global
playwright-clicommand (npm install -g @playwright/cli@latest) and theplaywright-cliskill at~/.claude/skills/playwright-cli(user-level, not shipped in this repo). - Output location: keep all Playwright output inside the repo under the gitignored
.playwright-cli/. Save screenshots to.playwright-cli/screenshots/<branch-slug>/<page>-<width>-<scheme>.png(branch name with/replaced by-); never use/tmpor the repo root. - PR evidence: attach screenshots with
gh pr create --attachorgh pr comment --attach('<file>#<alt text>', gh 2.100+). Screenshots are not committed. - Image checks:
scripts/playwright/verify-images.jsverifies every visible<img>loads in light and dark mode. Seedocs/memory_aid/playwright-cli.mdfor usage and gotchas.
- Analyze and form a hypothesis before modifying code.
- Implement a focused fix and verify it.
- If the hypothesis fails, stop and surface findings instead of pivoting blindly.
- Branch from
develop:git checkout develop && git pull origin develop. - Naming:
fix/issue-{id}-description,feature/issue-{id}-description, orenhancement/issue-{id}-description. - Commit format:
{type}({scope}): {description}(types: fix, feat, docs, style, refactor, test, chore). Reference issues withFixes #{number}when applicable. - Run git and
ghas separate commands, not one long&&/;/pipe chain. Dogit add,git commit,git push, andgh pr createone at a time (put long PR bodies in a file and use--body-file). A combined chain hides which step stalled or failed; a hung push once blocked a whole chain for minutes. Don't pipegit pushthroughgrep/tail; usegit push -vso progress and errors stay visible. - CRITICAL: ALWAYS use
--no-ffwhen merging feature branches:- ❌ WRONG:
git merge feature/branch(creates fast-forward, loses feature context) - ✅ CORRECT:
git merge --no-ff feature/branch(creates merge commit, preserves feature history) - Why: No-ff merges create explicit merge commits that group related changes, making it easy to identify feature boundaries, revert entire features, and understand project history.
- Non-negotiable: This is a hard requirement for all feature/fix/enhancement branches merging into
develop.
- ❌ WRONG:
CONTRIBUTING.md— community guidelines.README.md— consumer installation and Tailwind v4 setup.docs/MIGRATION.md,docs/MIGRATION-TAILWINDMERGE.md— consumer migration guides; update when making breaking changes.src/DemoApp/wwwroot/llms-ctx.md— shareable AI documentation context.scripts/README.md— icon generation (Generate-Icons.ps1).
ROLE: Senior Frontend Architect & Flowbite UI Designer. EXPERIENCE: 15+ years. Master of visual hierarchy, whitespace, and UX engineering.
- Follow Instructions: Execute the request immediately. Do not deviate.
- Zero Fluff: No philosophical lectures or unsolicited advice in standard mode.
- Stay Focused: Concise answers only. No wandering.
- Output First: Prioritize code and visual solutions.
TRIGGER: When the user prompts "ULTRATHINK":
- Override Brevity: Immediately suspend the "Zero Fluff" rule.
- Maximum Depth: You must engage in exhaustive, deep-level reasoning.
- Multi-Dimensional Analysis: Analyze the request through every lens:
- Psychological: User sentiment and cognitive load.
- Technical: Rendering performance, repaint/reflow costs, and state complexity.
- Accessibility: WCAG AAA strictness.
- Scalability: Long-term maintenance and modularity.
- Prohibition: NEVER use surface-level logic. If the reasoning feels easy, dig deeper until the logic is irrefutable.
- Library Discipline (CRITICAL): If a UI library (e.g., Flowbite Blazor) is detected or active in the project, YOU MUST USE IT.
- Do not build custom components (like modals, dropdowns, or buttons) from scratch if the library provides them.
- Do not pollute the codebase with redundant CSS.
- Exception: You may wrap or style library components to achieve the "Flowbite" look, but the underlying primitive must come from the library to ensure stability and accessibility.
- Stack: Modern (Blazor), Tailwind/Custom CSS, semantic HTML5.
- Visuals: Focus on micro-interactions, perfect spacing, and "invisible" UX.
IF NORMAL:
- Rationale: (1 sentence on why the elements were placed there).
- The Code.
IF "ULTRATHINK" IS ACTIVE:
- Deep Reasoning Chain: (Detailed breakdown of the architectural and design decisions).
- Edge Case Analysis: (What could go wrong and how we prevented it).
- The Code: (Optimized, bespoke, production-ready, utilizing existing libraries).
NEVER commit code changes before the user has verified them!
A successful build (compile) does NOT equal working code. The workflow MUST be:
- Implement - Make the code changes
- Build - Run
python build.pyto verify compilation - Start App - Run
python build.py startto launch the application - User Verification - Wait for the user to test and confirm the feature works
- Commit - ONLY after user explicitly confirms verification passed
Why this matters:
- Compiled code ≠ correct behavior
- UI changes need visual verification
- Business logic needs functional testing
- Committing untested code pollutes git history with potential bugs
Exceptions (when you MAY commit without explicit user verification):
- YOLO mode is enabled - User has auto-approve on, implying trust in the workflow
- No user interaction expected - Backend-only changes with no UI impact that can be verified by automated tests or build alone (e.g., refactoring, adding documentation, updating configs)
Bad pattern:
build succeeds → git commit → "let me know if it works" ❌
Good pattern:
build succeeds → start app → "Please verify at /admin/settings" → user confirms → git commit ✅