# Development
bun dev # Start dev server with Turbopack
bun build # TypeScript check + build with Turbopack
bun start # Start production server
# Code Quality
bun check-types # TypeScript type checking
bun lint # Run Biome linter
bun lint:fix # Auto-fix linting issues
bun format # Format code with Biome
bun test # Run tests- Use absolute imports with
@/alias - Separate type imports:
import type { Props } from '...' - Import order: React → Next.js → third-party → local → types
- Use arrow functions:
const Component = () => {} - Export components as named exports
- Define props with
typekeyword:type ComponentProps = {...} - Use
cn()utility for className merging - Apply variants with
class-variance-authority(cva)
- Components: PascalCase (
Message,CodeBlock) - Props types: Descriptive + "Props" suffix (
MessageProps) - Variants: descriptive names (
messageContentVariants) - Files: kebab-case for non-components
- Use TypeScript strict mode
- Handle async operations with proper error boundaries
- Validate props with TypeScript interfaces
- 2-space tabs (Biome configured)
- No semicolons (Biome removes them)
- Single quotes for strings
- Trailing commas in objects/arrays
Concise rules for building accessible, fast, delightful UIs Use MUST/SHOULD/NEVER to guide decisions
- Keyboard
- MUST: Full keyboard support per WAI-ARIA APG
- MUST: Visible focus rings (
:focus-visible; group with:focus-within) - MUST: Manage focus (trap, move, and return) per APG patterns
- Targets & input
- MUST: Hit target ≥24px (mobile ≥44px) If visual <24px, expand hit area
- MUST: Mobile
<input>font-size ≥16px or set:<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, viewport-fit=cover">
- NEVER: Disable browser zoom
- MUST:
touch-action: manipulationto prevent double-tap zoom; set-webkit-tap-highlight-colorto match design
- Inputs & forms (behavior)
- MUST: Hydration-safe inputs (no lost focus/value)
- NEVER: Block paste in
<input>/<textarea> - MUST: Loading buttons show spinner and keep original label
- MUST: Enter submits focused text input In
<textarea>, ⌘/Ctrl+Enter submits; Enter adds newline - MUST: Keep submit enabled until request starts; then disable, show spinner, use idempotency key
- MUST: Don’t block typing; accept free text and validate after
- MUST: Allow submitting incomplete forms to surface validation
- MUST: Errors inline next to fields; on submit, focus first error
- MUST:
autocomplete+ meaningfulname; correcttypeandinputmode - SHOULD: Disable spellcheck for emails/codes/usernames
- SHOULD: Placeholders end with ellipsis and show example pattern (eg,
+1 (123) 456-7890,sk-012345…) - MUST: Warn on unsaved changes before navigation
- MUST: Compatible with password managers & 2FA; allow pasting one-time codes
- MUST: Trim values to handle text expansion trailing spaces
- MUST: No dead zones on checkboxes/radios; label+control share one generous hit target
- State & navigation
- MUST: URL reflects state (deep-link filters/tabs/pagination/expanded panels) Prefer libs like nuqs
- MUST: Back/Forward restores scroll
- MUST: Links are links—use
<a>/<Link>for navigation (support Cmd/Ctrl/middle-click)
- Feedback
- SHOULD: Optimistic UI; reconcile on response; on failure show error and rollback or offer Undo
- MUST: Confirm destructive actions or provide Undo window
- MUST: Use polite
aria-livefor toasts/inline validation - SHOULD: Ellipsis (
…) for options that open follow-ups (eg, “Rename…”)
- Touch/drag/scroll
- MUST: Design forgiving interactions (generous targets, clear affordances; avoid finickiness)
- MUST: Delay first tooltip in a group; subsequent peers no delay
- MUST: Intentional
overscroll-behavior: containin modals/drawers - MUST: During drag, disable text selection and set
inerton dragged element/containers - MUST: No “dead-looking” interactive zones—if it looks clickable, it is
- Autofocus
- SHOULD: Autofocus on desktop when there’s a single primary input; rarely on mobile (to avoid layout shift)
- MUST: Honor
prefers-reduced-motion(provide reduced variant) - SHOULD: Prefer CSS > Web Animations API > JS libraries
- MUST: Animate compositor-friendly props (
transform,opacity); avoid layout/repaint props (top/left/width/height) - SHOULD: Animate only to clarify cause/effect or add deliberate delight
- SHOULD: Choose easing to match the change (size/distance/trigger)
- MUST: Animations are interruptible and input-driven (avoid autoplay)
- MUST: Correct
transform-origin(motion starts where it “physically” should)
- SHOULD: Optical alignment; adjust by ±1px when perception beats geometry
- MUST: Deliberate alignment to grid/baseline/edges/optical centers—no accidental placement
- SHOULD: Balance icon/text lockups (stroke/weight/size/spacing/color)
- MUST: Verify mobile, laptop, ultra-wide (simulate ultra-wide at 50% zoom)
- MUST: Respect safe areas (use env(safe-area-inset-*))
- MUST: Avoid unwanted scrollbars; fix overflows
- SHOULD: Inline help first; tooltips last resort
- MUST: Skeletons mirror final content to avoid layout shift
- MUST:
<title>matches current context - MUST: No dead ends; always offer next step/recovery
- MUST: Design empty/sparse/dense/error states
- SHOULD: Curly quotes (“ ”); avoid widows/orphans
- MUST: Tabular numbers for comparisons (
font-variant-numeric: tabular-numsor a mono like Geist Mono) - MUST: Redundant status cues (not color-only); icons have text labels
- MUST: Don’t ship the schema—visuals may omit labels but accessible names still exist
- MUST: Use the ellipsis character
…(not ``) - MUST:
scroll-margin-topon headings for anchored links; include a “Skip to content” link; hierarchical<h1–h6> - MUST: Resilient to user-generated content (short/avg/very long)
- MUST: Locale-aware dates/times/numbers/currency
- MUST: Accurate names (
aria-label), decorative elementsaria-hidden, verify in the Accessibility Tree - MUST: Icon-only buttons have descriptive
aria-label - MUST: Prefer native semantics (
button,a,label,table) before ARIA - SHOULD: Right-clicking the nav logo surfaces brand assets
- MUST: Use non-breaking spaces to glue terms:
10 MB,⌘ + K,Vercel SDK
- SHOULD: Test iOS Low Power Mode and macOS Safari
- MUST: Measure reliably (disable extensions that skew runtime)
- MUST: Track and minimize re-renders (React DevTools/React Scan)
- MUST: Profile with CPU/network throttling
- MUST: Batch layout reads/writes; avoid unnecessary reflows/repaints
- MUST: Mutations (
POST/PATCH/DELETE) target <500 ms - SHOULD: Prefer uncontrolled inputs; make controlled loops cheap (keystroke cost)
- MUST: Virtualize large lists (eg,
virtua) - MUST: Preload only above-the-fold images; lazy-load the rest
- MUST: Prevent CLS from images (explicit dimensions or reserved space)
- SHOULD: Layered shadows (ambient + direct)
- SHOULD: Crisp edges via semi-transparent borders + shadows
- SHOULD: Nested radii: child ≤ parent; concentric
- SHOULD: Hue consistency: tint borders/shadows/text toward bg hue
- MUST: Accessible charts (color-blind-friendly palettes)
- MUST: Meet contrast—prefer APCA over WCAG 2
- MUST: Increase contrast on
:hover/:active/:focus - SHOULD: Match browser UI to bg
- SHOULD: Avoid gradient banding (use masks when needed)
For playback engine (specifically, the audio manager/context), we have chosen the MediaBunny library.
-
MEDIA BUNNY LLMS ENTRY POINT: https://mediabunny.dev/llms.txt
-
MEDIA BUNNY TYPESCRIPT DEFINITIONS: https://mediabunny.dev/mediabunny.d.ts
-
MEDIA BUNNY INFO THROUGH CONTEXT7 MCP SERVER: https://context7.com/vanilagy/mediabunny/llms.txt?topic=how+would+one+architect+an+audio-daw+like+logic+pro+with+media+bunny+in+the+browser.
-
MEDIA BUNNY GUIDE: https://mediabunny.dev/guide/introduction
-
MEDIA BUNNY EXAMPLES: https://mediabunny.dev/examples
-
WEB AUDIO API DOCS: https://webaudio.github.io/web-audio-api/
- Firecrawl MCP for crawling, scraping, and more.
- Context7 MCP for docs - for instance, if you need up-to-date docs on the Web Audio API or React, you can use the context7 mcp to search the web for the latest docs. or if you want the latest React docs.