UI Component Library - Deep Dive Documentation¶

Generated: 2026-02-25 Scope: Sass-boilerplate-frontend-v1/src/components/ (ui/, custom/, editor/, layout/) Files Analyzed: 98 (40 ui/ + 34 custom/ + 15 editor/ + 9 layout/) Lines of Code: ~13,700 Known Issues Found: ~405 (9 Critical, 40 High, ~160 Medium, ~200 Low) Dead Code Files: 18 Workflow Mode: Exhaustive Deep-Dive Verification: Tailwind config verified, 5 user flows traced, modal/dialog audit completed

Overview¶

The UI Component Library is a four-layer system providing the visual foundation for the SaaS boilerplate frontend (Next.js 15 + React 19 + TailwindCSS 4):

Key Architectural Decisions: - shadcn/ui v2 pattern (no forwardRef, uses data-slot attributes) — React 19 compatible - class-variance-authority (cva) used only in button.jsx and badge.jsx - cn() from @/lib/utils (clsx + tailwind-merge) used in ~80% of components - Custom Tailwind tokens: text-light, text-light-4, text-light-50, shadow-box, border-gold, bg-gold - No test files exist for any component

Critical Issues Summary¶

Complete File Inventory¶

Layer 1: components/ui/ — 40 files, ~4,100 LOC¶

Radix UI Wrappers (17 files)¶

Library Wrappers (2 files)¶

CVA-Powered Components (2 files)¶

Custom Components (19 files)¶

Layer 2: components/custom/ — 34 files, ~6,700 LOC¶

Form Field Wrappers (8 files)¶

Layout & Display Components (14 files)¶

Navigation Components (4 files)¶

Modal & Dialog Components (3 files)¶

Auth & Permission Guards (2 files)¶

Feedback Components (5 files)¶

Layer 3: components/editor/ — 15 files, ~2,350 LOC¶

Layer 4: components/layout/ — 9 files, ~570 LOC¶

Dead Code Analysis¶

18 Files Never Imported (Total ~2,700 LOC)¶

Note: custom/dropdown-menu.jsx and custom/unauthorized-error.jsx initially flagged as dead but actually have consumers via relative imports. Corrected above.

Confirmed Dead: ~14 files, ~2,400 LOC removable¶

Cross-Cutting Issues¶

1. Accessibility Gaps (Systemic)¶

Components with ZERO accessibility: multi-select.jsx, loading.jsx, modal.jsx, dashboard-skeletons.jsx, all 3 carousels, all editor custom blocks

Common missing patterns: - aria-describedby for error messages (ALL form wrappers: input, checkbox, textarea, radio, date-picker, file-upload) - aria-required for required fields (ALL form wrappers show visual * only) - role="dialog" + aria-modal on modals (modal.jsx has neither) - Focus trap in modals/overlays (modal.jsx, unauthorized-error.jsx) - Keyboard navigation in custom dropdowns (multi-select.jsx, SearchableDropdown.jsx, all carousel thumbnails) - aria-label on icon-only buttons (copy button in code-box.jsx, password toggle in input.jsx)

Only spinner.jsx has proper accessibility (role="status", aria-label="Loading")

2. Duplicate / Near-Duplicate Components¶

3. Custom Tailwind Tokens (Require Config)¶

4. Export Pattern Inconsistencies¶

Default export files (inconsistent): author-card, code-box, heading, loading (ui/), analytic-card, breadcrumb2, button, confirmation-modal, data-not-found, mobile-navigation, navItem, toggle-switch, unauthorized-error (custom/)

5. Import Path Inconsistencies¶

6. Missing "use client" Directives¶

Components using hooks but missing the directive (work only because parents are client components):

7. Private API Access (Fragile)¶

4 editor files access TipTap internals that will break on upgrades: - editor._tiptapEditor._state?.doc?.textContent (BlocknoteEditor, BlocknoteViewer) - editor._tiptapEditor._state?.history$?.done?.items?.values (CustomToolbar) - editor._tiptapEditor.on("transaction", ...) (BlocknoteViewer, CustomToolbar)

Dependency Graph¶

Import Flow (Clean, Acyclic)¶

app/ pages/
    │
    ├──→ components/custom/   (form wrappers, layout widgets, modals)
    │       │
    │       └──→ components/ui/   (shadcn primitives, Radix wrappers)
    │               │
    │               └──→ @radix-ui/*, lucide-react, class-variance-authority, cmdk, react-day-picker
    │
    ├──→ components/layout/   (header, footer, navbar)
    │       │
    │       ├──→ components/custom/   (button, navItem, mobile-navigation)
    │       └──→ components/ui/       (skeleton, button)
    │
    ├──→ components/editor/   (BlockNote editor ecosystem)
    │       │
    │       └──→ @blocknote/*, @/lib/editor, @/lib/icons, @/lib/constant
    │
    └──→ components/ui/   (direct imports bypassing custom/ layer)

No circular dependencies detected. The flow is strictly downward.

Entry Points (not imported by other component files)¶

• All layout/*-wrapper.jsx files (server components, imported by app layouts)
• layout/footer-credit.jsx (imported by app layouts)
• editor/blocknote/TextEditor.jsx (imported by page components)
• All custom/ components (imported by page components)

Leaf Nodes (don't import other component files)¶

• ui/skeleton.jsx, ui/spinner.jsx, ui/input.jsx, ui/label.jsx (import only from @/lib/utils)
• ui/collapsible.jsx (imports only from Radix)
• custom/data-not-found.jsx (imports only lucide icon)

Integration Points¶

External Libraries¶

Redux Store Dependencies¶

Server Component Data Fetching¶

Contributor Checklist¶

Risks & Gotchas¶

1. Two Button components coexist: ui/button (shadcn, stateless) and custom/button (ripple effect, loading state). Pages import both inconsistently. Always use custom/button for interactive buttons, ui/button for composition inside other ui/ components.
2. Custom Tailwind tokens are project-specific: text-light, text-light-4, shadow-box, etc. must be defined in tailwind.config. If missing, styles silently fail.
3. Editor uses private TipTap APIs: Any BlockNote upgrade may break the toolbar, undo/redo, and text extraction.
4. modal.jsx has no focus trap or Escape key: Unlike dialog.jsx (Radix-based), the custom modal is not WCAG compliant for keyboard users.
5. SearchableDropdown case sensitivity: On Linux/CI (case-sensitive FS), SearchableDropdown.jsx and searchable-dropdown.jsx are different files. On Windows, they collide.
6. Form field wrappers hide description on error: checkbox.jsx, date-picker.jsx, and textarea.jsx all do !error && description, hiding potentially useful context.

Pre-Change Verification Steps¶

1. Search for all consumers of a component before modifying its props: grep -r "from.*components/ui/COMPONENT" src/
2. Check both @/components/ and ../ import patterns
3. Verify custom Tailwind tokens exist in tailwind.config.js
4. Test dark mode for any component with hardcoded colors
5. Test keyboard navigation for any interactive component

Suggested Tests¶

1. Keyboard navigation: Tab through all form components, verify focus ring visible on all button variants
2. Screen reader audit: Run axe-core on pages using modal.jsx, multi-select.jsx, loading.jsx
3. Dark mode visual check: All components with hardcoded hex colors (editor blocks, error/success pages, dashboard-skeletons)
4. Edge cases: pagination with 0 items, pricing-plan with empty data, slider with single value, date-inputs onChange on mount

Architecture & Design Patterns¶

Component Hierarchy Pattern¶

ui/ (primitives)         → shadcn/Radix wrappers, zero business logic
    ↑
custom/ (composed)       → Form fields with label/error/description
    ↑                      Layout widgets (cards, tables, modals)
    ↑                      Permission guards
pages/ (consumers)       → Import from both layers

Variant Management Approaches (4 different patterns)¶

1. CVA (button.jsx, badge.jsx): Best practice, type-safe, composable
2. Object map (alert.jsx, alerts.jsx, pricing-plan.jsx): Manual variant lookup
3. Data attributes (dropdown-menu.jsx data-variant): CSS-driven variants
4. Switch statement (custom/input.jsx, custom/textarea.jsx): Imperative, error-prone

State Management Patterns¶

Modification Guidance¶

To Add a New UI Primitive¶

1. Create file in src/components/ui/ following shadcn v2 pattern
2. Include "use client" if component uses hooks
3. Add data-slot="component-name" attribute
4. Use cn() for className merging
5. Export as named export: export { ComponentName }
6. If wrapping Radix, import primitives as namespace: import * as Primitive from "@radix-ui/react-*"

To Add a New Form Field Wrapper¶

1. Create file in src/components/custom/
2. Import base primitive from @/components/ui/ (use alias, not relative)
3. Follow the established pattern: label + input + error + description
4. Add aria-describedby linking error message to input (currently missing in all wrappers)
5. Use dynamic error IDs: ${id}-error not hardcoded strings

To Remove Dead Code¶

Safe to delete (zero consumers confirmed): - ui/author-card.jsx, ui/dashboard-skeletons.jsx, ui/searchable-dropdown.jsx (lowercase) - layout/navbar.jsx - editor/createEditor.jsx, editor/blocknote/BlocknoteViewer.jsx

Review before deleting (may be intentionally kept for future use): - ui/alert-dialog.jsx, ui/command.jsx (standard shadcn primitives, useful to keep) - custom/error-page.jsx, custom/success-page.jsx, custom/toggle-switch.jsx (functional, just unused)

Tailwind Token Verification (Against Actual Config)¶

The project uses Tailwind CSS v4 — all theme customization via @theme inline in globals.css (no tailwind.config.js).

Token Status¶

Critical: Gold Color Failure¶

These files reference undefined gold tokens — all gold styling is invisible: - ui/tabs.jsx — border-gold on active tab trigger - ui/multi-select.jsx — bg-gold/50, text-gold on selected items (4 uses) - custom/select.jsx — bg-gold/50, text-gold on selected values (2 uses) - components/blog-card.jsx — bg-gold, text-gold (3 uses) - pages/blogs/blogs-form.jsx — focus:border-gold on inputs (4 uses) - pages/pages/page-form.jsx — focus:border-gold (1 use) - dashboard/settings/profile/page.jsx — bg-gold, hover:bg-gold (1 use)

Fix Required for text-light-50¶

The CSS var exists in :root and .dark blocks but is missing from @theme inline:

/* Add to @theme inline block in globals.css: */
--color-light-50: var(--light-50);

Additional Config Issues¶

• --color-light is duplicated on lines 42-43 of globals.css @theme inline block
• --card is defined twice in :root (lines 63 and 92) — second definition wins
• --light-80 has CSS var but no @theme inline mapping (currently unused, no impact)

src/lib/utils.js Exports¶

Modal vs Dialog Audit¶

Three Competing Implementations¶

Plus 3 fully hand-rolled inline modals (email template HTML export/import, AI listening) with zero component reuse.

Consumer Map¶

custom/modal direct consumers (18 files): Settings (2FA setup, disable 2FA, backup codes, create setting), Contact details, Menu builder (old + v2: MenuSelector, EditItemDialog), Blog preview, Package details, Login (2FA), User form, Invite form, Customize manager (5+ instances), Role form, Permission form, Email templates (preview + save)

custom/confirmation-modal consumers (14 files): All destructive actions: delete setting, delete menu item, delete menu, delete contact, delete/restore/permanent-delete pages, blogs (6 instances), packages (6 instances), users (6 instances), invited users, permissions, permission groups, roles, email templates (6 instances)

Consolidation Recommendation¶

Phase 1 (Critical): Rewrite ConfirmationModal to wrap ui/alert-dialog instead of custom/modal. This fixes the 14 highest-risk consumers (all destructive actions) in one change. AlertDialog prevents accidental Escape dismissal of delete confirmations.

Phase 2: Create a DialogModal wrapper around ui/dialog matching the Modal/ModalHeader/ModalBody/ModalFooter API. Migrate the 18 form/detail consumers.

Phase 3: Migrate the 3 hand-rolled inline modals. Delete custom/modal.jsx.

User Flow Analysis (5 Flows Traced)¶

Component Consistency Matrix¶

Flow-Specific Findings¶

Flow 1 — Login: - 2FA modal during login uses custom/modal with zero accessibility — security-critical UI with no focus trap - "Remember Me" is a raw <input type="checkbox"> instead of ui/Checkbox - Cookie set with sameSite: "strict" storing JWT in non-httpOnly cookie

Flow 2 — Dashboard: - WelcomeSection references "Total Games" and "This Month Games" — gaming template remnant, not SaaS - Dead import: TopGamesUpvotes imported then BlogByAuthor re-imported from same file - Sidebar navigation is fully backend-driven via useNavigationLinks("dashboard-sidebar-top"/"bottom")

Flow 3 — Blog Create/Edit: - Triple PermissionWrapper nesting on create: page → page component → form component all check blog.create independently - Blog title/slug use raw native <input> elements, SEO fields use custom/Input, categories use ui/MultiSelect — 3 different input approaches in one form - Blog listing uses ui/button but blog form uses custom/button — different APIs/behavior - BlockNote editor integrates via react-hook-form Controller → TextEditor → BlocknoteEditorWrapper (dynamic, SSR=false) → BlocknoteEditor

Flow 4 — User Management: - PermissionWrapper (ALL required) vs NavPermissionWrapper (ANY required) logic mismatch for array permissions - User form submit button gated by permission="role.view" — misleading error message says "not enough permission to create a user" when actual missing permission is role.view - isInviteOnly checkbox is native <input type="checkbox"> while table rows use ui/Checkbox

Flow 5 — Landing Page: - All navigation is backend-driven (Menu Builder), but landing page content (features, testimonials, pricing, FAQ) is hardcoded in @/constants/landing-page-data - "Get Started" buttons in hero and header have no href or onClick — completely non-functional - layout/navbar.jsx exists but is never used — dead code superseded by header.jsx - PricingSection annual tab has pricing data hardcoded in JSX while monthly tab uses constants file

Cross-Flow Issues¶

1. Two Button components used interchangeably with no rationale: ui/button (shadcn, stateless, variant-based) vs custom/button (ripple effect, loading state, different variant names). Some pages use both.

2. Two Input components used interchangeably: ui/input (bare primitive) vs custom/input (wraps with label, error, password toggle). Blog form uses custom + native. User form uses ui.

3. PermissionWrapper called redundantly: Blog create has 3 nested checks for the same permission. This causes 3 sequential loading states and 3 independent error displays.

4. Native HTML elements mixed with component library: Native <input type="checkbox">, <input type="date">, <textarea>, and <input type="text"> appear alongside their component library equivalents in the same forms.

Security Analysis (Red Team vs Blue Team)¶

Full attack-defend analysis: docs/extra-docs/ui-component-attack-scenarios.md

5 Kill Chains Identified¶

Defense Gaps (Blue Team)¶

P0 Fixes (1.25 hours total)¶

1. Add sanitizer to GenericPage backend (45 min) — closes KC1
2. Add security headers to next.config.mjs (30 min) — closes KC1 + KC3

Generated by document-project workflow (deep-dive mode) — Exhaustive scan, 2026-02-25 Base Documentation: docs/index.md Analysis Mode: Exhaustive — every line of every file read by 14 parallel agent teams (9 scan + 3 verify + 2 security) Verification: Tailwind config tokens verified, 5 user flows traced end-to-end, modal/dialog audit completed Elicitation: Red Team vs Blue Team security analysis — 5 kill chains, defense gap matrix, hardening plan