@boeet/next-ui

Reusable React UI components extracted from the Next.js demo and aligned with design.md.

The next-ui name identifies the newer BOEET design-system line and separates it from earlier BOEET UI libraries. It does not mean this package can only be used in Next.js projects.

This package intentionally avoids Next.js-only APIs so it can be published to npm and consumed by Vite-based tools such as Figma Make.

Install

npm install @boeet/next-ui @boeet/next-tokens

For Tailwind v4, import the UI style entry once in the consumer app:

@import "tailwindcss";
@import "@boeet/next-ui/styles.css";

@boeet/next-ui/styles.css imports token variables and registers the built UI package as a Tailwind v4 source.

For Tailwind v3, import token CSS directly and add the package output to tailwind.config.* content.

@import "@boeet/next-tokens/styles.css";

Usage

import { Button } from "@boeet/next-ui/button"
import { Card, CardContent, CardHeader, CardTitle } from "@boeet/next-ui/card"

export function Example() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Energy Overview</CardTitle>
      </CardHeader>
      <CardContent>
        <Button>Submit</Button>
      </CardContent>
    </Card>
  )
}

Theme Switcher

Use ThemeSwitcher as a controlled UI component. Keep theme state management in the host app, for example with next-themes, and pass a normalized light or dark value into the component. The component renders the 52px x 26px icon switch used in the workbench header and does not manage html classes by itself. It has no visible label by default; pass label only when surrounding UI needs visible text.

import { useTheme } from "next-themes"
import {
  ThemeSwitcher,
  type ThemeMode,
} from "@boeet/next-ui/theme-switcher"

export function AppThemeSwitcher() {
  const { theme, setTheme } = useTheme()
  const currentTheme: ThemeMode = theme === "dark" ? "dark" : "light"

  return (
    <ThemeSwitcher
      value={currentTheme}
      onValueChange={setTheme}
      ariaLabel="切换深浅主题"
    />
  )
}

App Shell

Use SidebarAppShell or TopSidebarAppShell for admin-style pages that need the standard 244px sidebar, 64px top bar, 20px content padding, active navigation, expandable submenu, and mobile off-canvas navigation.

The app shell components do not depend on Next.js. Pass the current path from your router and optionally provide a custom link component. AppShell remains an alias of SidebarAppShell for compatibility.

For business applications, prefer headerPosition="fixed" so the layout header stays visible while the content scrolls. Fixed header mode adds the required content spacer and offsets the desktop header around the sidebar. The content area uses min-width: 0 and page-level horizontal overflow protection; wide tables and charts should scroll inside their own containers.

import type { ReactNode } from "react"
import {
  SidebarAppShell,
  TopSidebarAppShell,
  type AppShellLinkComponent,
  type AppShellNavItem,
} from "@boeet/next-ui/app-shell"

const navItems: AppShellNavItem[] = [
  { id: "overview", title: "Overview", href: "/overview" },
  {
    id: "examples",
    title: "业务示例",
    href: "/examples/admin",
    children: [
      { id: "examples-admin", title: "后台配置", href: "/examples/admin" },
      { id: "examples-forecast", title: "光伏预测", href: "/examples/forecast" },
    ],
  },
]

const LinkComponent: AppShellLinkComponent = ({ href, children, ...props }) => (
  <a href={href} {...props}>
    {children}
  </a>
)

export function AdminLayout({ children }: { children: ReactNode }) {
  return (
    <SidebarAppShell
      navItems={navItems}
      currentPath="/overview"
      linkComponent={LinkComponent}
      brand="Design Spec"
      headerTitle="综合能源管理平台"
      headerPosition="fixed"
      defaultExpandedIds={["examples"]}
    >
      {children}
    </SidebarAppShell>
  )
}

export function WorkbenchLayout({ children }: { children: ReactNode }) {
  return (
    <TopSidebarAppShell
      navItems={navItems}
      currentPath="/examples/microgrid"
      linkComponent={LinkComponent}
      brand="Design Spec"
      headerActions="User"
    >
      {children}
    </TopSidebarAppShell>
  )
}

Keep business-specific right rails or auxiliary card columns inside children; they are content layout, not app-shell slots.

Use design.md as the source of truth for visual rules and packages/figma-make-kit for Figma Make handoff guidance.