ui-component-architecture

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

UI component architecture

UI组件架构

The failure mode this corrects: an agent authors a screen as a few hundred lines of
<div className="...">
Tailwind soup — reimplementing a
Button
,
Card
, or
Badge
that already exists in the shared UI package, and never graduating the genuinely reusable pieces back into that package. The result is duplicated styling, drifting visual language, and screens nobody can read.
The fix is two habits: reuse before you author, and keep screens thin by extracting reusable units into the shared UI package — without over-extracting one-off layout glue. That package MUST be its own package. Its path and import alias are per-repo (ADR-0013). Discover them from the workspace (
package.json
workspaces,
packages/*
, vendor trees). Do not invent a required name.
Apply codebase-design when choosing component boundaries. Keep state, handlers, private components, and layout together when they explain one capability. An extraction should hide behavior or enable useful reuse; neither JSX length nor a second call site establishes that on its own.
它所纠正的问题模式:Agent编写的屏幕包含数百行
<div className="...">
式的Tailwind杂乱代码——重新实现了共享UI包中已有的
Button
、
Card
或
Badge
,并且从未将真正可复用的部分迁移回该包。这会导致样式重复、视觉语言漂移,以及可读性极差的屏幕代码。
解决方案包含两个习惯:先复用再编写,以及通过将可复用单元提取到共享UI包中来保持屏幕精简——但不要过度提取一次性的布局粘合代码。该UI包必须是独立的包。其路径和导入别名依仓库而定(ADR-0013)。可从工作区中查找(
package.json
的workspaces字段、
packages/*
目录、vendor目录树)。不要凭空设定一个强制的包名。
在选择组件边界时,请遵循codebase-design的规范。当状态、处理函数、私有组件和布局共同实现同一功能时,应将它们放在一起。提取组件应当是为了隐藏行为或实现有价值的复用;仅靠JSX长度或第二个调用场景不足以成为提取的理由。

When to use

适用场景

  • Authoring a new page/route/screen in an app that has a shared UI package.
  • Restyling or refactoring an existing screen that's heavy with inline divs.
  • Building a component that looks like a reusable primitive (button, card, badge, input, dialog, empty state, stat, skeleton, avatar).
  • The user says "build the X page", "add a Y view", "create a Z component".
  • 在拥有共享UI包的应用中编写新的页面/路由/屏幕。
  • 重新设计或重构一个充斥着大量内联div的现有屏幕。
  • 构建看起来属于可复用原语的组件(button、card、badge、input、dialog、empty state、stat、skeleton、avatar)。
  • 用户提出“构建X页面”、“添加Y视图”、“创建Z组件”等需求。

When NOT to use

不适用场景

  • Non-React code, or a single-package app with no shared UI package to reuse into.
  • A one-off layout wrapper with no independent responsibility to extract.
  • Editing the internals of one existing component, not adding a new surface.
  • 非React代码,或是没有可复用共享UI包的单包应用。
  • 没有独立职责、无需提取的一次性布局包装器。
  • 编辑单个现有组件的内部逻辑,而非新增新的对外组件。

Principles

原则

Reuse before you author

先复用后编写

Before writing JSX, inventory what already exists so you don't reinvent it:
  • The shared UI package — read its barrel or
    package.json
    exports
    . Grep for the thing you need.
  • External registries — for blocks not yet in the shared package, see the
    shadcn-registry-first
    skill. The flow is registry → app screen → graduate the stable pieces into the UI package.
Don't reimplement a
Button
,
Card
,
Badge
,
Input
,
Dialog
, or
EmptyState
that already exists.
在编写JSX之前,先盘点已有的组件,避免重复造轮子:
  • 共享UI包——查看其入口文件(barrel)或
    package.json
    的
    exports
    字段。搜索你需要的组件。
  • 外部组件注册表——对于尚未加入共享包的组件块,请参考
    shadcn-registry-first
    技能。流程为:组件注册表 → 应用屏幕 → 将稳定的组件迁移到UI包中。
不要重新实现已有的
Button
、
Card
、
Badge
、
Input
、
Dialog
或
EmptyState
组件。

Keep screens thin

保持屏幕精简

A route should make its data and major visual capabilities easy to follow. Compose existing primitives and extract components with a meaningful interface. Keep cohesive state and event handling with the UI they control. A component that only forwards a screen's props and markup adds navigation without hiding complexity. Private components may share a file with their owner.
路由对应的代码应当让其数据和主要视觉功能清晰易懂。组合现有原语组件,提取出具有有意义接口的组件。将内聚的状态和事件处理与它们所控制的UI放在一起。如果一个组件仅仅是转发屏幕的props和标记,那它只是增加了一层跳转,并没有隐藏复杂度。私有组件可以与其所属组件放在同一个文件中。

Graduate reusable units into the UI package

将可复用单元迁移到UI包

The load-bearing heuristic for what moves into the shared package:
  • Graduates: a reusable presentational unit with an independent interface, or a self-contained visual primitive —
    Button
    ,
    Card
    ,
    Badge
    ,
    Avatar
    ,
    EmptyState
    ,
    Stat
    ,
    Skeleton
    ,
    Input
    ,
    Dialog
    . Reuse in a second place is evidence to inspect; visual similarity alone does not establish one unit.
  • Stays in the app: app-specific composition (a particular dashboard's layout), one-off glue, and anything carrying data-wiring or business logic.
  • When unsure, leave it local. A single-use component can hide substantial behavior, but app-specific props belong in the app. A second use is a prompt to review the boundary, not to move app state into the shared package.
判断哪些内容应当迁移到共享包的核心启发式规则:
  • 应当迁移: 具有独立接口的可复用展示单元,或 自包含的视觉原语——如
    Button
    、
    Card
    、
    Badge
    、
    Avatar
    、
    EmptyState
    、
    Stat
    、
    Skeleton
    、
    Input
    、
    Dialog
    。在第二个场景中被复用是值得考察的信号;但仅靠视觉相似性不足以判定为一个可复用单元。
  • 应当保留在应用中: 应用特定的组合(例如某个特定仪表盘的布局)、一次性粘合代码,以及任何包含数据绑定或业务逻辑的内容。
  • 不确定时,保留在本地。 单次使用的组件可以隐藏大量行为,但应用特定的props应当留在应用中。出现第二次使用场景时,应当重新审视组件边界,而不是直接将应用状态迁移到共享包中。

Style with tokens and variants, not scattered magic values

使用令牌和变体样式,避免分散的魔法值

  • Use theme tokens (CSS variables, the Tailwind theme) — not raw hex literals sprinkled through
    className
    .
  • For components with variants, use a
    cn
    + variant map (or
    cva
    ) rather than conditional class-string soup.
  • Centralize styles for a reusable visual unit; keep incidental layout local.
  • 使用主题令牌(CSS变量、Tailwind主题)——不要在
    className
    中散落原始十六进制颜色值。
  • 对于有多款变体的组件,使用
    cn
    + 变体映射(或
    cva
    )的方式,而非条件式类名字符串堆砌。
  • 可复用视觉单元的样式应当集中管理;偶发的布局样式保留在本地。

Workflow

工作流程

1. Inventory the shared UI package

1. 盘点共享UI包

Find the package (workspace list,
packages/*
, vendor tree). List what it already exports. Note the primitives you'll reuse so you don't rebuild them.
找到该UI包(通过工作区列表、
packages/*
目录、vendor目录树)。列出它已导出的所有内容。记下你将要复用的原语组件,避免重复构建。

2. Sketch the screen as composition

2. 以组合的方式勾勒屏幕结构

Before writing detail, outline the page as a tree of named components. Tag each node: exists in the UI package / app-specific composition / new but looks reusable. This tells you what to import, what to inline, and what to extract.
在编写细节之前,先将页面拆解为命名组件树,勾勒出大致结构。为每个节点标记:UI包中已存在 / 应用特定组合 / 新增但看起来可复用。这样你就能清楚哪些需要导入、哪些可以内联、哪些需要提取。

3. Author the screen thin

3. 精简地编写屏幕代码

Compose existing primitives and keep each interaction understandable in one place. If a file exceeds its configured limit, split at a useful responsibility or document a narrow increase; file height alone does not select a component.
组合现有原语组件,将每个交互的逻辑都集中在一处,保持可读性。如果文件行数超出配置限制,按照合理的职责边界拆分,或是记录下小幅的阈值调整;仅靠文件长度不足以成为提取组件的理由。

4. Extract the reusable pieces

4. 提取可复用部分

For each piece that meets the graduation heuristic:
  • Put it in the UI package, next to its siblings.
  • Export it from the barrel or
    package.json
    exports
    .
  • Keep props generic — no app-specific types, routes, stores, or API clients leaking into a UI primitive. A shared UI component should be dumb and presentational; data comes in as props.
  • Co-locate variants with
    cn
    /
    cva
    .
对于每个符合迁移规则的部分:
  • 将其放入UI包中,与同类组件放在一起。
  • 通过入口文件(barrel)或
    package.json
    的
    exports
    字段导出。
  • 保持props的通用性——不要让应用特定的类型、路由、状态库或API客户端泄漏到UI原语中。共享UI组件应当是纯展示性的哑组件;数据通过props传入。
  • 将变体配置与
    cn
    /
    cva
    放在一起。

5. Verify

5. 验证

  • The screen imports primitives from the UI package rather than redefining them.
  • No app-specific imports (
    @/...
    , app routers, stores, API clients) inside any UI-package component.
  • Types and build pass using the repository's commands.
  • Interactions complete through the component's public interface; tests observe user behavior rather than its private hook or helper calls.
  • 屏幕从UI包导入原语组件,而非重新定义。
  • 任何UI包组件中都不得存在应用特定的导入(
    @/...
    、应用路由器、状态库、API客户端)。
  • 使用仓库的命令通过类型检查和构建。
  • 交互通过组件的公共接口完成;测试应关注用户行为,而非其内部的hook或辅助函数调用。

What graduates vs what stays

迁移与保留的边界

Stays in the appGraduates to the UI package
The
/dashboard
page layout
StatCard
,
Badge
,
EmptyState
Route-specific data fetching and wiring
Button
,
Input
,
Dialog
,
Skeleton
A hero used once on one marketing pageA hero variant reused across 3+ pages
Business logic, feature flags, app statePresentational primitives that take props
保留在应用中迁移到UI包
/dashboard
页面布局
StatCard
、
Badge
、
EmptyState
路由特定的数据获取和绑定逻辑
Button
、
Input
、
Dialog
、
Skeleton
仅在一个营销页面使用的hero组件在3个以上页面复用的hero变体
业务逻辑、功能开关、应用状态接收props的展示原语组件

Avoiding over-extraction

避免过度提取

Over-extraction is the opposite failure and just as costly. Signs you extracted too eagerly:
  • UI-package components with props named after one specific screen.
  • A component that forwards a long prop list without hiding an interaction or presentation decision.
  • UI primitives importing app stores, routers, or API clients.
Fix: keep app-specific behavior in a cohesive app component. Extract the shared primitive only when it has a useful presentational interface. Keep local helpers and private components nearby even when they are used once.
过度提取是另一种极端问题,代价同样高昂。过度提取的迹象:
  • UI包中的组件的props以某个特定屏幕命名。
  • 组件只是转发一长串props,并没有隐藏任何交互或展示逻辑。
  • UI原语导入了应用的状态库、路由器或API客户端。
修复方法:将应用特定的行为保留在内聚的应用组件中。仅当共享原语具有有价值的展示接口时才提取它。本地辅助函数和私有组件即使只使用一次,也应放在靠近使用处的位置。

Reference

参考资料

  • reference/agents-md-rule.md
    — a short, paste-able always-on rule for a consuming repo's
    AGENTS.md
    . This is the highest-leverage lever: skills are loaded on demand and can under-trigger on "every UI edit," whereas an
    AGENTS.md
    rule is always in context. Drop it into each repo that has a shared UI package; fill in that repo's actual package path and import alias.
  • reference/eslint-guardrails.md
    — lint rules that enforce the boundaries mechanically (no raw hex in app JSX, capped JSX depth, and — most importantly — a boundary rule banning app imports inside the UI package).
  • reference/agents-md-rule.md
    —— 一段简短的、可直接粘贴的常驻规则,用于使用方仓库的
    AGENTS.md
    文件。这是最高效的手段:技能是按需加载的,在“每次UI编辑”时可能触发不足,而
    AGENTS.md
    规则则始终在上下文中生效。将其放入每个拥有共享UI包的仓库中;填写该仓库实际的包路径和导入别名。
  • reference/eslint-guardrails.md
    —— 以机械方式强制执行边界的lint规则(应用JSX中禁止原始十六进制颜色值、限制JSX深度,以及——最重要的——禁止在UI包内部导入应用代码的边界规则)。

Relationship to other skills

与其他技能的关系

  • shadcn-registry-first
    — sources external blocks from registries. This skill governs internal reuse and extraction. They compose: registry → app screen → graduate stable pieces into the UI package.
  • darkmatter-design-system
    — visual language and tokens when the app uses that system. Those tokens still live in the UI package; this skill is the package boundary.
  • repository-organization
    — where directories and packages live. This operates one level down, at the component-reuse granularity.
  • vercel-react-best-practices
    — performance patterns for the components you write and compose.
  • shadcn-registry-first
    —— 从组件注册表获取_外部_组件块。本技能管理_内部_的复用与提取。二者相互配合:组件注册表 → 应用屏幕 → 将稳定的组件迁移到UI包中。
  • darkmatter-design-system
    —— 应用使用该系统时的视觉语言和令牌。这些令牌仍存放在UI包中;本技能关注的是包的边界。
  • repository-organization
    —— 目录和包的存放位置。本技能在更细的粒度上运作,即组件复用层面。
  • vercel-react-best-practices
    —— 你所编写和组合的组件的性能优化模式。