设计原则

指导 HeroUI v3 设计和开发的核心原则

HeroUI v3 遵循 10 项核心原则，注重清晰度、无障碍、可定制性以及开发者体验。

核心原则

1. 语义意图优于视觉风格

使用语义命名（primary、secondary、tertiary），而非视觉描述（solid、flat、bordered）。灵感来自 Uber 的 Base 设计系统，变体遵循清晰的层次结构：

1// ✅ Semantic variants communicate hierarchy2<Button variant="primary">Save</Button>3<Button variant="secondary">Edit</Button>4<Button variant="tertiary">Cancel</Button>

变体	用途	使用方式
Primary	推进流程的主要操作	每种场景 1 个
Secondary	备选操作	可使用多个
Tertiary	次要操作（取消、跳过）	谨慎使用
Danger	破坏性操作	需要时使用

2. 无障碍是基础

基于 React Aria Components 构建，符合 WCAG 2.1 AA 标准。内置自动 ARIA 属性、键盘导航与屏幕阅读器支持。

1import { Tabs, TabList, Tab, TabPanel } from '@lenso/ui';2
3<Tabs defaultSelectedKey="profile">4  <TabList aria-label="Settings">5    <Tab id="profile">Profile</Tab>6    <Tab id="security">Security</Tab>7  </TabList>8  <TabPanel id="profile">Content</TabPanel>9  <TabPanel id="security">Content</TabPanel>10</Tabs>

3. 组合优于配置

复合组件允许你按需重新组合、自定义或省略其中的各个部分。可以使用点号语法、命名导出，或两者混合使用。

1// Compose parts to build exactly what you need2import {3  Accordion,4  AccordionItem,5  AccordionHeading,6  AccordionTrigger,7  AccordionIndicator,8  AccordionPanel,9  AccordionBody10} from '@lenso/ui';11
12<Accordion>13  <AccordionItem id="1">14    <AccordionHeading>15      <AccordionTrigger>16        Question Text17        <AccordionIndicator />18      </AccordionTrigger>19    </AccordionHeading>20    <AccordionPanel>21      <AccordionBody>Answer content</AccordionBody>22    </AccordionPanel>23  </AccordionItem>24</Accordion>

4. 渐进式呈现

从简单开始，仅在需要时才增加复杂度。组件只需最少的 props 即可工作，并能随需求增长而扩展。

1// Level 1: Minimal2<Button>Click me</Button>3
4// Level 2: Enhanced5<Button variant="primary" size="lg">6  <Icon icon="gravity-ui:check" className="mr-2" />7  Submit8</Button>9
10// Level 3: Advanced11<Button variant="primary" isDisabled={isLoading}>12  {isLoading ? <><Spinner size="sm" className="mr-2" /> Loading...</> : 'Submit'}13</Button>

5. 可预测的行为

所有组件遵循一致的模式：尺寸（sm、md、lg）、变体、className 支持以及 data 属性。相同的 API，相同的行为。

1// All components follow the same patterns2<Button size="lg" variant="primary" className="custom" data-pressed="true" />3<Chip size="lg" variant="success" className="custom" />4<Avatar size="lg" className="custom" />5
6// Compound components support both named exports and dot notation7import { Alert, AlertIcon, CardHeader, AccordionTrigger } from '@lenso/ui';8
9// Named exports10<Alert>11  <AlertIcon />12</Alert>13
14// Dot notation15<Alert>16  <Alert.Icon />17</Alert>

6. 类型安全优先

完整的 TypeScript 支持，包括 IntelliSense、自动补全与编译时错误检测。可为自定义组件扩展类型。

1import type { ButtonProps } from '@lenso/ui';2
3// Type-safe props and event handlers4<Button5  variant="primary"  // Autocomplete: primary | secondary | tertiary | danger | ghost6  size="md"          // Type checked: sm | md | lg7  onPress={(e) => {  // e is properly typed as PressEvent8    console.log(e.target);9  }}10/>11
12// Extend types for custom components13interface CustomButtonProps extends Omit<ButtonProps, 'variant'> {14  intent: 'save' | 'cancel' | 'delete';15}

7. 样式与逻辑分离

样式（@lenso/tokens）与逻辑（@lenso/ui）相互分离，可与任何框架或纯 HTML 一同使用。参见 Tailwind Play 示例。

1<!-- Use with plain HTML -->2<button class="button button--primary">Click me</button>

或与 React 一同使用：

1// Apply styles to any component2import { buttonVariants } from '@lenso/tokens';3
4<Link className={buttonVariants({ variant: "primary" })} href="/home">5  Home6</Link>

8. 卓越的开发者体验

清晰的 API、富含信息的错误提示、IntelliSense、对 AI 友好的 Markdown 文档，以及用于可视化测试的 Storybook。

9. 完全可定制

开箱即用的精美默认样式。使用 CSS 变量或 BEM 类即可彻底改变整体外观。每一个插槽都可定制。

1/* Theme-wide changes with variables */2:root {3  --accent: oklch(0.7 0.25 260);4  --radius: 0.375rem;5  --spacing: 0.5rem;6}7
8/* Component-specific customization */9@layer components {10  .button {11    @apply uppercase tracking-wider;12  }13  .button--primary {14    @apply bg-gradient-to-r from-purple-500 to-pink-500;15  }16}

10. 开放且可扩展

可以包装、扩展或自定义组件以满足你的需求。可以使用变体函数、直接应用 BEM 类，或创建自定义的包装组件。

使用变体函数应用样式：

1import { Link } from '@lenso/ui';2import { linkVariants } from '@lenso/tokens';3import NextLink from 'next/link';4
5// Use variant functions to style framework-specific components6const slots = linkVariants({ underline: "hover" });7
8<NextLink className={slots.base()} href="/about">9  About Page10  <Link.Icon className={slots.icon()} />11</NextLink>

直接应用 BEM 类：

1import Link from 'next/link';2
3// Apply HeroUI's BEM classes directly to any element4<Link className="button button--primary" href="/dashboard">5  Dashboard6</Link>

创建自定义包装组件：

1// Custom wrapper component2const CTAButton = ({3  intent = 'primary-cta',4  children,5  ref,6  ...props7}: CTAButtonProps) => {8  const variantMap = {9    'primary-cta': 'primary',10    'secondary-cta': 'secondary',11    'minimal': 'ghost'12  };13
14  return (15    <Button ref={ref} variant={variantMap[intent]} {...props}>16      {children}17    </Button>18  );19};

使用 Tailwind Variants 扩展：

1import { Button } from '@lenso/ui';2import { buttonVariants, tv } from '@lenso/tokens';3
4// Extend button styles with custom variants5const myButtonVariants = tv({6  extend: buttonVariants,7  variants: {8    variant: {9      'primary-cta': 'bg-gradient-to-r from-blue-500 to-purple-600 text-white shadow-lg',10      'secondary-cta': 'border-2 border-blue-500 text-blue-500 hover:bg-blue-50',11    }12  }13});14
15// Use the custom variants16function CustomButton({ variant, className, ...props }) {17  return <Button className={myButtonVariants({ variant, className })} {...props} />;18}19
20// Usage21<CustomButton variant="primary-cta">Get Started</CustomButton>22<CustomButton variant="secondary-cta">Learn More</CustomButton>

与 HeroUI v2 的对比

维度	HeroUI v2	HeroUI v3
动画	Framer Motion	CSS + GPU 加速
组件模式	带有大量 props 的单一组件	复合组件
变体	基于视觉（solid、bordered、flat）	基于语义（primary、secondary、tertiary）
样式	部分支持 Tailwind v4	完整支持 Tailwind v4
无障碍	优秀（基于 React Aria）	优秀（基于 React Aria）
打包体积	较大（整体打包）	较小（支持 tree-shaking）
自定义难度	中等（基于 props）	简单（复合组件 + 原生 CSS）