Interface Craft & Motion Rules
Relevant source files
The following files were used as context for generating this wiki page:
Interface Craft & Motion Rules define the aesthetic and interactive standards for the Kocteau platform. The project prioritizes a "dark, editorial, human-led music review experience" that feels closer to a quiet music journal or premium product like Letterboxd rather than a generic social network or SaaS dashboard.
Sources: AGENTS.md:5-9, README.md:594-597
Visual Identity and Product Truths
The visual language of Kocteau is rooted in minimalism, monochrome palettes, and editorial precision. The interface is designed to disappear behind the content—music reviews—which are treated as the "main event".
Core Visual Principles
- Atmosphere: Dark, quiet, premium, and slightly cinematic through tone rather than decorative effects.
- Color Restraint: Primarily monochrome. Color is used only for specific functional accents like star ratings or natural album art. Neon, gradients, and typical SaaS colors are explicitly avoided.
- Typography: Strong focus on legibility and supporting music identity. The system uses Geist for sans-serif and Merriweather for headings.
- Hierarchy: The primary column carries the experience, with reviews dominating the visual hierarchy.
Sources: AGENTS.md:12-23, AGENTS.md:104-129, apps/web/app/layout.tsx:11-20
Visual Element Standards
| Element | Rule |
|---|---|
| Borders | Thin, subtle dividers; concentric radii for nested surfaces. |
| Shadows | Avoid oversized shadows; favor restrained contrast. |
| Spacing | Calm, intentional empty space; stable geometry. |
| Text | Balanced wrapping for headings; tabular numbers for side-by-side values. |
Sources: AGENTS.md:123-138
Interaction and Motion Rules
Motion in Kocteau is used sparingly and only when it improves clarity. The objective is to maintain a stable, non-distracting reading flow.
Motion Implementation
- Library: Uses
motion/react(Framer Motion) for UI transitions. - Philosophy: Motion should be "cinematic through tone" rather than decorative.
- Reduced Motion: Components must respect user preferences for reduced motion, often bypassing animations when
useReducedMotionis active. - Loading States: Uses structural skeletons that mirror final layouts to prevent layout shifts. Spinners are reserved for small inline actions only.
Sources: AGENTS.md:111-112, AGENTS.md:231-236, apps/web/components/auth/onboarding-flow-preview.tsx:142-155
Onboarding Flow Interaction
The onboarding process utilizes AnimatePresence and motion.div to provide smooth transitions between profile and taste setup steps.
This diagram represents the sequential step-based motion flow during user onboarding.
Sources: apps/web/components/auth/onboarding-flow-preview.tsx:57-123, apps/web/components/auth/onboarding-flow-preview.tsx:162-175
Layout Architecture
The layout is designed to prioritize the "reading flow" and minimize competing focal points.
- Primary Column: Center column contains search, feed filters, and reviews.
- Navigation: Left sidebar remains stable and functional.
- Editorial Rail: Right rail is an "editorial companion" providing discovery, trends, and curated picks. It must not feel like a "social sidebar" or ad column.
Sources: AGENTS.md:141-158
Feed Layout Structure
The architecture separates navigation, the primary reading experience, and contextual editorial discovery.
Sources: AGENTS.md:154-158, AGENTS.md:164-169
Component Craft
Components are split by product intent rather than UI fragments. Visual polish is applied through cn(...) for class composition and tailwind-based styling.
Design Engineering Mindset
- Stable Dimensions: Prevent layout shift by using known image dimensions and consistent spacing.
- Optical Alignment: Align elements (like icons and text) optically rather than just geometrically.
- Shaders: Specific decorative backgrounds (e.g.,
DitheringShader) are used in containers like the Feed Review CTA to create texture without introducing loud gradients.
Sources: AGENTS.md:65-74, AGENTS.md:135, apps/web/components/feed-review-cta.tsx:32-48
UI Component Examples
| Component | Craft Detail |
|---|---|
| Review Card | Prioritizes track identity, cover art, and the written take; avoids dense metadata. |
| Skeletons | Mirror final layouts; preserve spacing and stay calm/dark. |
| Dialogs | Trap and restore focus; avoid hydration mismatches. |
| Inputs | Fast and reliable; do not block paste. |
Sources: AGENTS.md:195-200, AGENTS.md:231-236, AGENTS.md:247-251
Email Visual System
The editorial craft extends to transactional emails, maintaining the "minimal dark" aesthetic.
- Color Palette: Background
#070707, Panel#0d0d0d, Primary Text#f7f4ee. - Typography: Uses System UI stack for reliability; external web fonts are avoided for consistency across clients.
- Logo: PNG is used instead of SVG for broader support; the logo is not rounded via CSS.
Sources: apps/web/emails/README.md:38-66
Summary
The Interface Craft & Motion Rules ensure that Kocteau remains a high-trust, human-centric platform. By enforcing a dark, minimal, and editorial design language, the system directs all user attention toward music discovery and the quality of reviews. Interaction is kept stable and functional, using motion only to reinforce the user's progress through product loops.
Sources: AGENTS.md:310-318