UI Component Kit
Relevant source files
The following files were used as context for generating this wiki page:
The UI Component Kit serves as the visual contract and central repository for all reusable interface elements within the RateGuru project. It is primarily accessed via the /dev/ui-kit route and provides developers with a live environment to verify components against the "PlateRate" reference direction. The kit ensures consistency across the application by enforcing the use of design tokens and predefined Blade components rather than arbitrary Tailwind utilities.
Sources: resources/views/dev/ui-kit.blade.php:7-12, AGENTS.md:46-51
Architecture and Design Principles
The UI architecture follows a strict hierarchy where reusable UI is encapsulated in Blade components. Local UI state, such as toggling modals or drawers, is handled by Alpine.js, while server-side state (forms, voting, comments) is managed by Livewire.
Design Contract Constraints
- Environment Restriction: The UI Kit is only accessible in
localandtestingenvironments; it is hidden with a 404 error in production. - Token Usage: Components must use RateGuru-specific tokens (e.g.,
bg-rg-bg,text-rg-text) to maintain visual fidelity with the design contract. - Source of Truth: The PlateRate Reference Composition is the visual source of truth for Phase 1+ product UI.
Sources: AGENTS.md:52-58, tests/Feature/DevUiKitRouteTest.php:20-24, tests/Feature/ApplicationShellTest.php:11-16
Component Hierarchy
The UI Kit categorizes components into four distinct levels of abstraction:
This diagram shows the relationship between high-level reference layouts and the underlying primitive building blocks.
Sources: resources/views/dev/ui-kit.blade.php:15-103
Reference Composition
The platerate-reference-composition is a static visual contract representing the Phase 1 product direction. It simulates the full application shell, including the topbar, sidebar, and feed.
Core Regions
| Region | Data Attribute | Description |
|---|---|---|
| Shell | platerate-shell | The main container (max-width 1440px) with rounded corners and shadows. |
| Topbar | platerate-topbar | Fixed header (60px height) containing search and branding. |
| Sidebar | platerate-sidebar | Navigation area (240px width) containing categories and tags. |
| Feed | platerate-feed | Main content area for post cards and tabs. |
| Detail Column | platerate-detail-column | Right-side panel for results and comments (380px-460px). |
Sources: resources/views/dev/partials/platerate-reference-composition.blade.php:7-13, tests/Feature/DevUiKitRouteTest.php:84-95, tests/Feature/ApplicationShellTest.php:27-35
Component Categories
Primitive Components
Primitives are the foundational building blocks used across all modules.
- Buttons: Support multiple variants including
primary,secondary,ghost,danger, andelevated. - Cards: Defined by the
x-ui.cardcomponent with variants forpanel,post,selected-post,results, andcomment. - Forms: Includes
x-ui.input,x-ui.textarea, and specialized components likex-ui.error-message.
Sources: resources/views/dev/ui-kit.blade.php:107-175, tests/Feature/DevUiKitRouteTest.php:26-55
Overlays and Feedback
Overlays utilize Alpine.js for local state management (open state).
This sequence illustrates the interaction flow for overlay components defined in the kit.
Sources: resources/views/dev/ui-kit.blade.php:181-229, AGENTS.md:58
Feed and Voting Components
These components are driven by real Post data shapes and Livewire for server-side interaction.
- Vote Rail: Displays scores and handles up/down voting actions.
- Binary Choice: A specialized toggle for "Homemade vs Restaurant" logic.
- Cuisine Chips: Categorization pills used for tagging and filtering.
- Source Options: Renders voting options for post origins.
Sources: resources/views/dev/ui-kit.blade.php:48-93, tests/Feature/DevUiKitRouteTest.php:97-106
Implementation Example: Sidebar Navigation
The sidebar uses a loop to render navigation links, applying active state styling based on the current route.
<nav class="space-y-1">
@foreach ($nav as [$label, $icon, $active])
<a href="#" class="{{ $active ? 'border-rg-border2 bg-rg-card2 text-rg-text' : 'border-transparent text-rg-text2 hover:bg-rg-card hover:text-rg-text' }} flex h-10 items-center gap-3 rounded-rgControl border px-3.5 text-[13.5px] font-semibold">
<x-ui.icon :name="$icon" class="size-4" />
{{ $label }}
</a>
@endforeach
</nav>
Sources: resources/views/dev/partials/platerate-sidebar.blade.php:13-22
Summary
The UI Component Kit is a mandatory reference point for developers. According to the AGENTS.md rules, every reusable component must be rendered in this kit, and developers must compare new implementations against the PlateRate Reference Composition to ensure adherence to the design contract. This system centralizes visual state, reduces Tailwind utility bloat, and maintains a strict separation between local Alpine.js state and server-side Livewire state.
Sources: AGENTS.md:46-60