Web Design System & UI Components
Relevant source files
The following files were used as context for generating this wiki page:
The Kocteau design system is built to facilitate a "dark, editorial, human-led music review experience." It deviates from standard SaaS dashboard aesthetics, opting instead for a minimal, cinematic feel reminiscent of a quiet music journal or high-end editorial platform. The system prioritizes the reading and reviewing experience through restrained use of color, stable geometry, and intentional spacing.
The system is implemented using a modern web stack including Next.js, Tailwind CSS, and shadcn/ui. It emphasizes a "Design Engineering" mindset where UI is prototyped quickly and refined to maintain a high level of "interface craft."
Sources: AGENTS.md:4-10, README.md:104-113
Core Visual Language
The visual direction of Kocteau is defined by a monochrome palette, subtle dividers, and high-quality typography. The goal is to avoid "loud" elements like heavy gradients, oversized shadows, or colorful pills that contribute to UI noise.
Design Principles
- Restrained Contrast: Using soft dark surfaces and thin borders instead of high-contrast containers.
- Stable Geometry: Maintaining consistent dimensions to prevent layout shifts.
- Editorial Spacing: Utilizing empty space intentionally to support the reading flow.
- Restrained Color: Color is used only for specific functional accents (e.g., star ratings) or provided naturally by album/track cover art.
Sources: AGENTS.md:120-155
Typography and Iconography
The system utilizes specific font stacks to maintain its editorial character:
- Sans-serif: Geist (via
next/font/google) is used for primary UI and body text. - Heading: Merriweather is used for serif-style editorial headings.
- Icons: The system leverages HugeIcons and custom SVG glyphs (like the
ReviewGlyphIcon).
Sources: apps/web/app/layout.tsx:11-23, apps/web/package.json:28-29
Layout Architecture
The layout follows a strict hierarchy designed to keep the music review as the "main event." The interface is generally split into a primary column for the core experience and secondary rails for discovery.
Layout diagram showing the relationship between navigation, the primary feed, and the editorial rail.
Sources: AGENTS.md:159-172
Navigation and Sidebar
The sidebar (AppSidebar) acts as the stable functional anchor of the application. It is designed to be quiet and collapsible, using shadcn/ui sidebar primitives. It houses primary navigation (Feed, Explore), user-specific actions (Saved, Activity), and the "New Review" launcher.
Sources: apps/web/components/app-sidebar.tsx:45-155
Component System
Components in Kocteau are split by "product intent" rather than arbitrary UI fragments. They are built using class-variance-authority (CVA) for variant management and tailwind-merge (cn utility) for class composition.
Key UI Components
| Component | Description | Logic/Features |
|---|---|---|
AppSidebar | Main navigation shell | Handles collapsible states, active path detection, and keyboard shortcuts (e.g., 'N' for review). |
FeedReviewCta | Inline call-to-action for reviews | Uses DitheringShader for cinematic visual effect and integrates NewReviewDialog. |
ReviewPageCard | Primary unit for displaying a review | Prioritizes track identity, cover image, and written content. |
ReviewCommentsPanel | Interaction layer for reviews | Manages inline replies and comment counts. |
Sources: AGENTS.md:350-365, apps/web/components/feed-review-cta.tsx:28-55, apps/web/app/(main)/review/[id]/page.tsx:135-155
Motion and Interaction
Motion is used sparingly through motion/react (formerly framer-motion) and only when it improves clarity. Common interactions include:
- Hover/Active States: Scale transforms (e.g.,
active:scale-[0.96]) and subtle background color transitions. - Layout Transitions: Sidebar uses a
180msease-out transition. - Skeletons: Structural skeletons are preferred over spinners for main page loading to preserve spacing and dimensions.
Sources: AGENTS.md:105-110, AGENTS.md:384-395, apps/web/components/app-sidebar.tsx:113
Email Visual System
The design system extends to transactional emails, maintaining parity with the dark editorial theme of the web app. Emails are built using React Email.
Email Configuration
| Attribute | Value |
|---|---|
| Background | #070707 |
| Panel | #0d0d0d |
| Primary Text | #f7f4ee |
| Border Radius | 12px (CTA), 18px (Code), 24px (Panel) |
| Logo Format | PNG (to ensure cross-client compatibility) |
Sources: apps/web/emails/README.md:43-70
Technical Implementation
The design system is implemented via Tailwind CSS configuration and a global CSS file that defines theme variables and custom utilities.
Theme Variables
The system uses CSS variables for consistent theming, particularly for line colors and radii.
--kocteau-line-soft: Used for subtle borders on badges and cards.--kocteau-radius-card: Standardized border radius for review cards.--kocteau-ease: Custom easing function for smooth UI transitions.
Sources: apps/web/components/feed-review-cta.tsx:32, apps/web/components/app-sidebar.tsx:113
Class structure showing the shared utility heritage of UI components.
Sources: AGENTS.md:104-108, apps/web/package.json:34-40
Conclusion
The Web Design System of Kocteau is a specialized implementation focused on "Quiet Discovery." By avoiding typical SaaS growth-hacking UI patterns (like noisy badges and bright accents), the system creates a premium environment for music reviews. Its reliance on Next.js Server Components and a centralized component library ensures that visual polish is achieved without compromising performance or layout stability.