@gener8v/ui

中文文档
0.64.0发布于 2026/11/10MITTypeScriptES Module零依赖近 30 天下载 4740

React components for the GENER8V design system — the same class names as its static HTML, so markup ports either direction.

原始使用文档
文档目录6 节
  1. The one thing to understand
  2. Where this sits
  3. What is in here
  4. Conventions this package holds to
  5. Peer dependencies
  6. Changing something here

@gener8v/ui

The React layer of the GENER8V design system.

npm i @gener8v/ui          # public on npm, MIT
import '@gener8v/ui/styles.css';   // once, at the app root
import { Button, Flow, BarChart } from '@gener8v/ui';

The one thing to understand

These components render the same class names as the design system's static HTML.

<!-- design/components/buttons.html -->
<button type="button" class="btn btn-primary">Continue</button>
<Button variant="primary">Continue</Button>
// → <button type="button" class="btn btn-primary">Continue</button>

That is not a coincidence and it is not decoration — it is the property the whole system is built around. HTML written against the design system (including HTML Claude generates, because design/readme.md teaches it these classes) drops into a React app with no visual rewrite. And a component here can never quietly diverge from the documented look, because pnpm lint:parity fails if the static HTML uses a class no component can emit.

If you find yourself adding a className that is not in design/styles.css, stop. Either the class belongs in the system — add it to packages/tokens/src/components/ and a preview page — or you are styling something locally that should not be styled locally.

Where this sits

packages/tokens/src/theme.mjs      the source of truth — 135 tokens
        │
        ├──▶ design/styles.css     the only stylesheet; shipped here as dist/styles.css
        │            │
        │            ├──▶ design/**.html     static pages, the visual reference
        │            └──▶ @gener8v/ui        this package — same classes
        │
        ├──▶ @gener8v/tokens       the same values as JS/JSON, for logic
        └──▶ @gener8v/tailwind-preset   the same values as Tailwind utilities

@gener8v/icons is independent — 18 Phosphor glyphs, no dependency on this package.

What is in here

267 exports across 52 families. The ones worth knowing:

AreaExports
ActionsButton ButtonGroup
SurfacesCard CardLink Panel Tag
FormsField Input Textarea Select Combobox Checkbox Radio Switch Slider FileUpload TokenInput Quantity RadioCard
NavigationNav Sidebar Breadcrumbs Tabs Tree Hamburger Drawer PagerChip Contents Menu CommandPalette Kbd ShortcutList useListKeys
FlowFlow Stepper Progress Meter Timeline Feed Lanes LiveProgress LiveIndicator Pulse LiveMark LiveSection State StateArt useStepValidation ErrorSummary
FeedbackDialog Alert Toast ToastProvider/useToast Tooltip Popover HoverCard useDelegatedHoverCard Callout ToolChip ConfirmCard
DataTable usePagedTable TablePager Matrix Diff Stat DescriptionList Avatar BarChart LineChart Sparkline KnowledgeGraph LayeredGraph
Library & integrationsDocList DocPreview Reader Citation SourceCard Connection Credential KeyRow Rule

design/components/*.html shows every one of them rendered. View source and copy the markup.

Conventions this package holds to

State lives in ARIA, not in a class. NavItem takes current and emits aria-current="page"; Th takes sort and emits aria-sort; Input takes invalid and emits aria-invalid. The CSS styles the attribute. There is no .is-active, and the visual and the accessibility tree cannot drift apart.

Accessibility is enforced by types where it can be. An icon-only Button requires aria-label — it is a compile error without one, not a review comment.

Behaviour is real, or the component says it is not. Dialog and Drawer share useModalBehavior: Escape closes, focus moves in and returns to the trigger, Tab cycles, background scroll locks with a depth counter for nesting. Tabs, Tree, Menu, Combobox and Calendar each implement their full WAI-ARIA keyboard contract. Where something is genuinely unfinished — Tooltip ships the surface but not collision-aware positioning — the doc comment says so rather than pretending.

Native elements wherever one exists. Slider is <input type="range">; FileUpload wraps a real file input hidden with .sr-only, never display: none, so it stays in the tab order. Reimplementing these loses keyboard behaviour, value announcement and form participation, and usually gets at least one of them wrong.

Dates cross the boundary as YYYY-MM-DD strings, never Date objects. A Date carries a time and a zone; a calendar date has neither.

A masked secret is not in the DOM. Credential renders a substitute string and only mounts the real value once revealed — a CSS mask leaves the secret in the markup and in any DOM snapshot.

Peer dependencies

React 18 or 19. Nothing else — no component library, no icon set, no chart library, no form-validation library. That is deliberate: each would make every consumer inherit a choice the design system has no business making for an application.

Changing something here

This package is one of six outputs of one source. Read the repository root README before editing, run pnpm check before calling anything done, and add the class to packages/tokens/src/components/ plus a preview page in design/components/ — a component that emits a class the design system does not document will fail the parity gate.

版本与发布记录

@gener8v/ui 共发布 80 个版本,首次发布于 2026/08/24;过去 12 个月发布了 80 个版本。

版本发布日期距今
0.64.0latest2026/11/106 天前
0.63.02026/11/0511 天前
0.62.02026/11/0511 天前
0.61.02026/11/0411 天前
0.60.02026/11/0412 天前
0.59.12026/11/0312 天前

关于 @gener8v/ui 的常见问题

@gener8v/ui 是什么?

React components for the GENER8V design system — the same class names as its static HTML, so markup ports either direction.

如何安装 @gener8v/ui?

在项目目录运行 npm install @gener8v/ui,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(>=18)、react-dom(>=18)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gener8v/ui 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gener8v/ui 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gener8v/ui 可以商用吗?

@gener8v/ui 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gener8v/ui 的下载量有多少?

根据 npm 官方下载统计,@gener8v/ui 在 2026/10/16 – 2026/11/14 这 30 天内被下载 4,740 次,日均约 158 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gener8v/ui 还在维护吗?

最新版本 0.64.0 发布于 2026/11/10(6 天前);至今共发布 80 个版本,其中过去 12 个月发布了 80 个;首次发布于 2026/08/24。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。