Product & Design Principles
Relevant source files
The following files were used as context for generating this wiki page:
Kocteau is a music review and taste discovery platform built with a focus on "human taste" and "quiet discovery." Unlike generic social networks or productivity-driven SaaS dashboards, Kocteau is designed as a dark, editorial, and human-led experience. It prioritizes the act of reviewing music and expressing personal taste over social growth-hacking or algorithmic noise.
The project follows a "design engineering" mindset where the goal is to create a cinematic, minimal, and premium interface. Every technical and design decision is governed by the core mission of making music reviewing easier and discovery feel more human, maintaining an atmosphere closer to a quiet music journal or an editorial curation service like Apple Music or Letterboxd.
Sources: AGENTS.md:5-10, README.md:12-14
Core Product Truths & Loop
Kocteau is defined by a specific set of "Product Truths" that establish the hierarchy of the user experience. Reviews are the primary event, and the "For You" feed serves as the home experience, driven by human taste signals rather than complex, automated black-box algorithms.
The Product Loop
The system is designed to protect and improve a specific cyclical user journey:
- Entry: Users join via email OTP (One-Time Password).
- Onboarding: Completion of profile and initial taste signal selection.
- Action: Reviewing a specific track.
- Interaction: Engaging with the community through likes, bookmarks, comments, or follows.
- Discovery: Returning to a personalized "For You" feed that evolves based on behavior.
Sources: AGENTS.md:14-41, README.md:85-93
The following diagram illustrates the lifecycle of a user within the Kocteau ecosystem:
The Kocteau Product Loop ensures that every user action directly feeds back into the discovery experience.
Sources: AGENTS.md:33-41, README.md:104-114
Visual & Interface Direction
The visual identity of Kocteau is intentionally restrained to support a focused reading and listening experience. The design principles emphasize a "dark" and "editorial" feel, utilizing a mostly monochrome palette.
Visual Constraints
- Restraint with Color: Use of color is limited to rating accents or natural colors from album/track covers. SaaS-like gradients, neons, or "glow-heavy" styling are explicitly avoided.
- Typography & Geometry: The interface favors strong typography for headings, stable geometry to prevent layout shift, and thin, subtle dividers.
- Micro-polish: Design engineering focuses on small details such as concentric border radii for nested surfaces and optical alignment for icons and text.
| Principle | Description | Avoid |
|---|---|---|
| Tone | Dark, cinematic, and quiet. | Loud, decorative effects. |
| Surfaces | Soft dark surfaces with thin borders. | Heavy shadows or glassmorphism. |
| Layout | One strong reading flow; stable dimensions. | Competing focal points; layout shifts. |
| Copy | Concise, human, and music-native. | Corporate/growth-hacking jargon. |
Sources: AGENTS.md:75-121, AGENTS.md:204-222
Layout Principles
The application layout follows a strict functional hierarchy:
- Left Sidebar: Stable and quiet; contains navigation and primary actions.
- Center Column: The primary carrier of the experience, containing search, filters, and reviews.
- Right Rail: Lean editorial companion (e.g., Editor’s picks, "Fresh voices") rather than a social "Who to follow" widget.
Sources: AGENTS.md:130-143, AGENTS.md:150-165
Content & Editorial Logic
Kocteau differentiates itself by treating reviews as the "main event" and ensuring that recommendations feel editorial rather than purely mathematical.
Review UI Rules
A review card must prioritize track identity and the reviewer's written take. It should avoid becoming a dense dashboard object filled with excessive metadata or loud engagement counters. If a user leaves only a rating, the UI must present that state gracefully.
Recommendation Logic
Recommendations are routed through a hybrid system:
- Explicit Signals: Taste tags chosen by the user during onboarding.
- Inferred Signals: Affinity derived from liked/bookmarked reviews and author follows.
- Editorial Fallbacks: "Starter picks" are used when data is sparse. These are curated prompts, not fake reviews, designed to provide a high-quality cold-start experience.
Sources: AGENTS.md:180-200, README.md:188-212
The recommendation system uses a routing layer to prioritize human behavior while providing curated fallbacks.
Sources: README.md:188-204
Technical Execution & Code Quality
Kocteau adopts a "boring" technical approach, favoring direct logic and existing patterns over clever abstractions.
Stack Defaults
The project is built on a modern, performance-oriented stack:
- Framework: Next.js App Router (Server components by default).
- Database/Auth: Supabase (Auth, Postgres, RLS, and RPCs).
- Styling: Tailwind CSS with shadcn/ui components.
- State: TanStack Query for interactive client-side state.
Sources: AGENTS.md:58-69, README.md:116-126
Performance & Accessibility
- Perceived Speed: Use of structural skeletons that mirror final layouts to avoid layout jumping.
- Accessibility: Mandatory keyboard support,
focus-visiblestates, and generous hit targets for mobile users. - Metadata: Dynamic generation of SEO-friendly metadata for reviews, profiles, and tracks to improve discovery outside the platform.
Sources: AGENTS.md:275-290, AGENTS.md:295-310, apps/web/lib/metadata.ts:98-120
Security & Contributions
The repository enforces a strict "local-first" development workflow using the Supabase CLI. Security is handled through Row Level Security (RLS) and email OTP-first authentication. Contributors are encouraged to focus on small, impactful changes like UI polish or accessibility improvements rather than rewriting core auth or recommendation logic.
Sources: CONTRIBUTING.md:10-25, README.md:144-155, CODE_OF_CONDUCT.md:3-10
Conclusion
Kocteau’s design and product principles center on creating a high-signal, low-noise environment for music lovers. By combining a cinematic, dark aesthetic with an editorial approach to discovery, the platform seeks to return the focus of music sharing to human taste. The project's technical architecture supports this by prioritizing server-side stability, accessibility, and a focused product loop that rewards meaningful interaction over passive consumption.
Sources: AGENTS.md:368-375, README.md:237-240