Components Overview

Honeycomb’s frontend uses a layered component architecture. Low-level UI primitives live in $lib/components/ui/, while higher-level layout and shared components are organized under $lib/modules/.

UI Library Stack

Layer	Package	Role
Primitive headless components	bits-ui ^2.16	Accessible, unstyled building blocks (Dialog, Select, DropdownMenu, etc.)
Styled component library	shadcn-svelte	Pre-styled wrappers around bits-ui, added via CLI
Variant system	tailwind-variants ^3.2	tv() utility for defining component variants (replaces cva)
Styling	Tailwind CSS v4	Utility-first CSS with the slate base color palette

Tip

shadcn-svelte components are copied into your codebase, not installed as a package dependency. This means you own the code and can freely modify any component in $lib/components/ui/.

Directory Structure

src/lib/
├── components/
│   ├── ui/                    # shadcn-svelte primitives
│   │   ├── button/
│   │   ├── input/
│   │   ├── dialog/
│   │   ├── data-table/
│   │   ├── chart/
│   │   ├── sidebar/
│   │   ├── sonner/
│   │   └── ...35+ components
│   ├── app-sidebar.svelte     # Example/demo sidebar (shadcn scaffold)
│   └── marketing/             # Landing page components
├── modules/
│   ├── layout/                # AppSidebar, SiteHeader, breadcrumbs
│   └── shared/                # EmptyState, LoadingSkeleton, MobileNav, etc.

Component Categories

UI Primitives

Button, Input, Select, Dialog, Card, Badge, Tabs, Sheet, Drawer, Tooltip, and more. See UI Primitives.

Layout

AppSidebar, SiteHeader, SidebarRight, MobileNav, and the automatic breadcrumb system. See Layout Components.

Data Display

DataTable powered by TanStack Table and Charts powered by LayerChart + D3. See Data Display.

Feedback

Toast notifications, loading skeletons, empty states, and confirmation modals. See Feedback Components.

Configuration

The project root contains a components.json that the shadcn-svelte CLI reads:

{
  "$schema": "https://shadcn-svelte.com/schema.json",
  "tailwind": {
    "css": "src/routes/layout.css",
    "baseColor": "slate"
  },
  "aliases": {
    "components": "$lib/components",
    "utils": "$lib/utils",
    "ui": "$lib/components/ui",
    "hooks": "$lib/hooks",
    "lib": "$lib"
  },
  "typescript": true,
  "registry": "https://shadcn-svelte.com/registry"
}

Adding New Components

From the shadcn-svelte registry

Use the CLI to add a component from the registry. This copies the source files into $lib/components/ui/:

npx shadcn-svelte@latest add <component-name>

For example, to add the popover component:

npx shadcn-svelte@latest add popover

This creates $lib/components/ui/popover/ with the component files and an index.ts barrel export.

Creating custom components

When building a new feature-level component (not a generic primitive):

1. Place it inside the relevant module directory under $lib/modules/<feature>/components/.
2. Re-export it from the module’s index.ts barrel file.
3. Import UI primitives from $lib/components/ui/ — never duplicate them.

Caution

Do not modify components inside $lib/components/ui/ unless you are intentionally overriding the default shadcn-svelte behavior. If you just need a styled variant, extend the existing tv() variants in the component’s module-level script block instead.

Variant conventions

Honeycomb uses tailwind-variants (tv()) for variant definitions. Each component exports its variant types for external consumption:

<script lang="ts" module>
  import { tv, type VariantProps } from "tailwind-variants";

  export const myComponentVariants = tv({
    base: "...",
    variants: {
      size: { sm: "...", md: "...", lg: "..." },
      variant: { default: "...", outline: "..." },
    },
    defaultVariants: { size: "md", variant: "default" },
  });

  export type MyComponentVariant = VariantProps<typeof myComponentVariants>["variant"];
</script>