@inf-monkeys-tech/monkeys-design
v2.0.425
Published
Monkeys Design Components Library
Readme
@inf-monkeys-tech/monkeys-design
Monkeys Design 是一个独立的 React 组件库,提供可复用的基础组件、数据展示组件、主题工具和样式资源。
本轮核心 UI 的 54 个组件从 @inf-monkeys-tech/monkeys-design/components/ui 引用,并加载 @inf-monkeys-tech/monkeys-design/ui.css。全部组件实现新建,状态为 beta;核心组件与 ThemeProvider 共 55 个独立文档入口、226 个逐组件示例。RecordView 按卡片、列表行、详情、预览区分布局,内容和业务规则由调用方提供。另行开发的特效组件不计入这组覆盖统计。参见接入说明、元素覆盖与组件索引和验证记录。
公开文档
Monkeys Design 的官网与组件文档由
monkeys-docs 统一维护和部署:
- 官网:https://docs.infmonkeys.com/monkeys-design
- 组件目录:https://docs.infmonkeys.com/monkeys-design/components
本仓库继续通过 Storybook 维护组件开发、交互测试、无障碍检查和视觉回归;examples/public/ 是官网组件页与 Storybook 共享的公开示例来源。
安装
yarn add @inf-monkeys-tech/monkeys-design或:
npm install @inf-monkeys-tech/monkeys-design使用
从主入口导入通用能力:
import {
applyThemeTokens,
compileThemeTokens,
} from "@inf-monkeys-tech/monkeys-design";ThemeTokens 是唯一主题输入。Design 不接收旧主题配置,不提供转换器、别名或并行版本入口。
从子路径导入组件:
import {
BaseButton,
BasePanel,
type BaseAppearance,
} from "@inf-monkeys-tech/monkeys-design/components/base";
const appearance: BaseAppearance = {
preset: "soft",
radius: "lg",
border: "subtle",
background: "soft",
};
export function Example() {
return (
<BasePanel
appearance={appearance}
title="Design System"
description="Composable UI primitives for Monkeys products."
footer={<BaseButton appearance={appearance} label="Refresh" />}
>
Content stays in the consuming application.
</BasePanel>
);
}包入口
四象限 QuadrantCanvas 和自研力导图 RelationshipGraph2D 可从
@inf-monkeys-tech/monkeys-design/components/visualizations 导入;同时引入
@inf-monkeys-tech/monkeys-design/styles.css。配置、宿主回调和性能边界见
原生可视化组件。
| 路径 | 内容 |
| ----------------------------------------------------------- | --------------------------------------------------------------- |
| @inf-monkeys-tech/monkeys-design | 主入口,导出通用组件、主题工具和公共类型 |
| @inf-monkeys-tech/monkeys-design/components/base | 基础组件 |
| @inf-monkeys-tech/monkeys-design/components/beautiful | 来自 Beautiful UI 的 BUIxxxx 系列组件 |
| @inf-monkeys-tech/monkeys-design/beautiful.css | Beautiful UI 系列的独立样式 |
| @inf-monkeys-tech/monkeys-design/components/data-explorer | 数据展示与页面组合组件 |
| @inf-monkeys-tech/monkeys-design/components/login | 登录相关 UI 组件 |
| @inf-monkeys-tech/monkeys-design/components/layout | 布局组件 |
| @inf-monkeys-tech/monkeys-design/components/toolbar | 工具栏组件 |
| @inf-monkeys-tech/monkeys-design/components/capabilities | 声明式 Capability Catalog、provider/renderer runtime 与中性能力 |
| @inf-monkeys-tech/monkeys-design/palette | palette 工具 |
| @inf-monkeys-tech/monkeys-design/theme-system | canonical ThemeTokens 编译与应用工具 |
Beautiful UI(BUI 系列)
BUIButton、BUIPromptBar、BUISidebarNav 等 BUIxxxx 组件来自开源项目
Beautiful UI(上游源码)。
该系列按照上游 MIT 许可证接入,保留版权与许可声明,并适配 Monkeys Design 的组件命名、主题、语言和声明式装配入口。
这一系列包含 34 个公共组件,保留 Beautiful UI 的基础组件和视觉风格,使用独立样式入口:
import { BUIButton } from '@inf-monkeys-tech/monkeys-design/components/beautiful';
import '@inf-monkeys-tech/monkeys-design/beautiful.css';
<BUIButton>Continue</BUIButton>Storybook 中的独立分组为 Beautiful UI,条目名称与组件导出一致。
演示数据与示例状态放在 stories/beautiful,组件的数据和操作回调由调用方提供。
BUISidebarNav 使用现有 Lucide 图标替代上游的 Central Icons,因此图标形状有所不同。
完整用法、声明式入口、上游版本和接入差异见 Beautiful UI README; 版权与许可证见 MIT License。
Task feed
任务记录展示组件从 @inf-monkeys-tech/monkeys-design/components/workbench 导入:
WorkbenchTaskCard、WorkbenchTaskToolbar、WorkbenchTaskOutputs、WorkbenchTaskMedia 和 WorkbenchTaskPrompt。
它们只处理展示与界面交互,数据请求、结果权限和操作副作用由调用方负责。
参见 组件契约、组合示例
及 Storybook 的 Workbench/WorkbenchTaskFeed。
LoginPage
LoginPage 是通用登录页 UI 组件。组件库只负责页面结构和样式契约,不包含登录请求、OAuth、路由、租户判断、i18n 初始化或租户定制样式。
import {
LoginPage,
type LoginPageMethodConfig,
} from "@inf-monkeys-tech/monkeys-design/components/login";
import "@inf-monkeys-tech/monkeys-design/styles/login-page.scss";
const methods: LoginPageMethodConfig[] = [
{
id: "email",
label: "Email",
fields: [],
submitLabel: "Login",
onSubmit: (event) => event.preventDefault(),
},
];
export function Example() {
return (
<LoginPage
background={{ imageUrl: "", gradient: "" }}
logo={{ url: "", position: "bottom", scale: 1 }}
toolbar={<div />}
title="Welcome"
methods={methods}
/>
);
}默认背景规则:
- 配置了
background.imageUrl或background.gradient时,使用配置背景。 - 未配置背景时,浅色模式使用白色和主题色渐变。
- 未配置背景时,
.dark深色模式使用黑色和主题色渐变。
Logo 规则:
logo.url是浅色和深色模式共用的通用 Logo。logo.lightUrl/logo.darkUrl分别用于浅色 / 深色模式;未配置时回退logo.url。- 宿主应用负责在登录页未单独配置 Logo 时,把品牌资产的浅色 / 深色 Logo 传入
logo.lightUrl/logo.darkUrl。
LoginPage 不接受原始颜色、圆角或任意 CSS props。宿主应用必须先用 applyThemeTokens 应用后端下发的 DTCG Token 合同,组件只消费统一的 --primary、--primary-foreground、--radius 等语义变量;深浅色切换、语言切换等应用级控件通过 toolbar 传入。
LoginPage CSS 契约
页面级自定义样式只能依赖 data-login-page、data-login-part 和公开 CSS 变量。不要依赖租户 id,不要新增登录页代码分支。
推荐优先覆盖变量:
[data-login-page] {
--login-page-panel-bg: rgb(255 255 255 / 0.92);
--login-page-panel-border: rgb(17 17 17 / 0.08);
--login-page-panel-shadow: 0 24px 60px rgb(0 0 0 / 0.08);
--login-page-control-bg: #ffffff;
--login-page-control-border: rgb(17 17 17 / 0.12);
--login-page-control-text: #111111;
--login-page-control-placeholder: #9f9fa9;
--login-page-form-width: 500px;
}
.dark [data-login-page] {
--login-page-panel-bg: rgb(12 12 12 / 0.9);
--login-page-control-bg: #111111;
}公开部件:
[data-login-part="root"] {
}
[data-login-part="background"] {
}
[data-login-part="toolbar"] {
}
[data-login-part="logo"] {
}
[data-login-part="logo-image"] {
}
[data-login-part="panel"] {
}
[data-login-part="back"] {
}
[data-login-part="back-icon"] {
}
[data-login-part="title"] {
}
[data-login-part="tabs"] {
}
[data-login-part="tab"] {
}
[data-login-part="tab-icon"] {
}
[data-login-part="form"] {
}
[data-login-part="field"] {
}
[data-login-part="input"] {
}
[data-login-part="checkbox-label"] {
}
[data-login-part="checkbox"] {
}
[data-login-part="method-footer"] {
}
[data-login-part="method-footer-action"] {
}
[data-login-part="submit-button"] {
}
[data-login-part="callout"] {
}
[data-login-part="callout-title"] {
}
[data-login-part="callout-description"] {
}
[data-login-part="callout-detail"] {
}
[data-login-part="callout-action"] {
}
[data-login-part="external-methods"] {
}
[data-login-part="external-label"] {
}
[data-login-part="external-list"] {
}
[data-login-part="external-button"] {
}
[data-login-part="external-icon"] {
}基础组件
基础组件从 components/base 子路径导入:
import {
BaseButton,
BaseContextMenu,
BaseContextMenuContent,
BaseContextMenuItem,
BaseContextMenuTrigger,
BasePanel,
type BaseAppearance,
} from "@inf-monkeys-tech/monkeys-design/components/base";当前包含:
BaseButtonBaseBadgeBasePanelBaseEmptyStateBaseLoadingStateBaseFieldBaseInputBaseTextareaBaseSelectBaseLayoutBaseLayoutPaneBaseLayoutSplitBaseLayoutResizeHandleBaseSwitchBaseCheckboxBaseRadioGroupBaseDialogBaseDropdownMenuBaseTooltipBaseTableBaseTableFooterBarBaseNoticeBaseDividerBaseSectionHeaderBaseTabsBaseSegmentedControlBaseProgressBaseSkeletonBaseAvatarBaseToolbarBaseBreadcrumbBasePaginationBaseDescriptionListBaseAccordionBaseContextMenu
BaseAppearance 用于控制 preset、density、radius、border、background、slot className 和 inline style 覆盖。
BaseLayout 提供中立布局 primitives:BaseLayout 管 header/sidebar/main/aside/footer 区域,BaseLayoutPane 管主题化区域表面,BaseLayoutSplit 管固定或可调的左右/上下分割。gap 可显式控制区域间距,number 按 px,string 原样作为 CSS 长度;不传时继续使用 BaseAppearance 的主题间距。可调分割支持 defaultSize、受控 size、minSize、maxSize 和 onSizeChange;尺寸是否持久化仍由使用方控制。
Data Explorer
components/data-explorer 提供面向数据密集页面的组合组件。组件库负责可复用的控制、展示、预览、详情和布局结构;数据请求、权限、路由、弹窗和业务动作由使用方控制。
import {
DataExplorerView,
type DataExplorerViewDefinition,
} from "@inf-monkeys-tech/monkeys-design/components/data-explorer";常用组件包括:
DataExplorerViewDataExplorerViewCollectionDataExplorerDisplayCardDataExplorerDisplayCollectionViewDataExplorerDisplayActionMenuDataExplorerDetailShellDataExplorerImagePreviewDataExplorerToolbarShellDataExplorerActionBarDataExplorerTreeDataExplorerPage
声明式 Capability Catalog
components/capabilities 提供编辑器可发现的显式 Capability Catalog,以及基于 SDK CapabilityManifest、ViewProviderDescriptor、RenderNode 和 RenderTree 合同的 provider/renderer runtime。中性能力包括 shell/layout、sidebar/filter、gallery、record history/diff、Ontology/View management action launcher、统一 loading/empty/error/forbidden 状态、generic view capability leaf,以及可序列化的 section header、notice、description list、content panel 和 toolbar。管理操作组件只发出精确、受治理的流程或命令 intent,不直接调用业务 API。metadata/declarative-capability-audit.json 逐项声明受治理 Base 组件和公开组件族是否可进入页面构建器;React export 本身不会产生 Capability。
Catalog 只包含 NEUTRAL_CAPABILITY_CATALOG_ENTRIES 中明确声明的条目。导出一个 React 组件不会自动使它成为可装配能力;新增能力必须同时声明 SDK manifest、provider descriptor、editor slots、ports、Ontology compatibility、i18n keys、token refs、a11y 与 performance evidence,再显式注册 provider 和 renderer。
import {
CapabilityRuntimeHost,
NEUTRAL_DESIGN_CAPABILITY_RUNTIME,
} from "@inf-monkeys-tech/monkeys-design/components/capabilities";
export function DeclarativePage({ tree, access, bindings, t }) {
return (
<CapabilityRuntimeHost
tree={tree}
runtime={NEUTRAL_DESIGN_CAPABILITY_RUNTIME}
access={access}
bindings={bindings}
translate={t}
/>
);
}有 accessRef 的节点必须收到调用方已经计算好的 access decision;缺失 decision 时 runtime 默认 forbidden,并且不会执行 provider。异步 provider 收到 AbortSignal,在 binding、访问状态或生命周期变化时取消旧请求并阻止 stale result 覆盖;onPerformanceEvidence 会收到 success、empty、error、cancelled 或 budget-exceeded 证据。Design 不负责计算业务权限,不拥有 Ontology 数据,不解释 raw API payload,也不把专业编辑器内部展开成第二棵 RenderTree。
主题系统
theme-system 只接受 DTCG 2025.10 ThemeTokens 文档,负责严格校验、解析引用、编译 CSS variables 和应用运行轴。类型和运行时 Schema 唯一来源是 @inf-monkeys-tech/monkeys。
import {
applyThemeTokens,
compileThemeTokens,
} from "@inf-monkeys-tech/monkeys-design/theme-system";
const compiled = compileThemeTokens(themeTokens, {
colorMode: "light",
density: "default",
});
applyThemeTokens(themeTokens);compileThemeTokens 支持 DTCG Group、$root、$extends、curly alias、JSON Pointer 和全部 13 种标准类型。light/dark 通过独立 Token 路径选择,不能塞进 $value。applyThemeTokens 只向指定 host root 写 canonical/semantic CSS variables 与 data-monkeys-* 运行轴,并会清除上一次应用留下的变量;它不读取产品业务字段。
Base 组件统一通过 variant、density、state 与 appearance 表达视觉和交互状态。组件不得把客户名、租户 ID、路由、页面场景或 raw API 字段作为视觉分支条件。
样式资源
可从包内直接引用样式文件:
import "@inf-monkeys-tech/monkeys-design/styles.css";
import "@inf-monkeys-tech/monkeys-design/styles/global.scss";
import "@inf-monkeys-tech/monkeys-design/styles/workflow-nodes.css";styles.css 提供 canonical 产品控件的 Design-owned surface Token。它们不继承宿主页面的 --background、--popover 或 --card,因此不同产品 palette 不会改变同一标准控件的默认表面:
| Public CSS variable | Consumers | Light default | Dark default |
| --------------------------------- | ----------------------------------------------- | ---------------- | ----------------- |
| --monkeys-color-control-surface | Input、Textarea、outline Button、Select Trigger | 240 20% 99.02% | 240 6% 7% |
| --monkeys-color-menu-surface | Select/Dropdown content | 240 20% 99.02% | 270 3.85% 10.2% |
| --monkeys-color-dialog-surface | Dialog/AlertDialog content | 240 20% 99.02% | 240 6% 7% |
宿主若有经过评审的产品主题差异,可以在加载 styles.css 后显式覆盖对应的 --monkeys-* variable;不要通过 feature className 或泛化页面 Token 重写 canonical surface。未加载 styles.css 属于集成错误。
Storybook
本仓库内置 Storybook,用于预览和调试组件:
npm run storybook构建静态 Storybook:
npm run storybook:build开发
# 安装依赖
npm install
# 开发模式
npm run dev
# 构建生产产物
npm run build
# 类型检查
npm run typecheck
# 合同、token compiler 与标准组件 props 测试
npm run test
# 检查实际发布文件
npm run pack:check
# 代码检查
npm run lintbuild scans public TypeScript component exports and regenerates assembly metadata before compilation. It then emits dist/artifacts/design-capability-catalog.json, exported as @inf-monkeys-tech/monkeys-design/artifacts/design-capability-catalog.json in the npm package. prepack and prepublishOnly run this build; a separate generate:assembly invocation is optional. Inventory or compilation failures stop packaging. TypeScript declarations are emitted once into .declarations/, then bundled from those declarations using the same public entry map as the JavaScript build. This avoids repeatedly expanding generated schemas while preserving the public type exports. Watch mode continues to compile declarations from source.
Component validation at publication
Published component rendering trusts declarations checked by the publication pipeline.
Loading an adapter and calling render do not compile or run the full property schema.
Optional assembly groups and event arguments still receive their runtime defaults;
slot/host lookup, event projection and the direct HTML restriction remain in place.
For authoring or publication, call adapter.validate(model) explicitly, or use the
server entry point below. The server entry loads descriptors and schemas without
React or DOM dependencies and caches validators by component ID:
import { componentAssemblyValidationLoaders } from '@inf-monkeys-tech/monkeys-design/components/assembly/validation';
const validator = await componentAssemblyValidationLoaders.BaseButton();
validator.validate({ contract: 'ComponentAssembly', schemaVersion: 1, props: { children: 'Save' } });Publication must check the effective static model (instance properties merged with
the node model), including fixed query projection models. Dynamic query results are
still governed by the service's result contracts. Deploy the publication validator
with a Design package containing this entry point before rolling out the browser
rendering change. Existing callers that need validation during a preview must invoke
validate explicitly; runtime localization does not repeat full property validation.
Published capability IDs keep a stable runtimeContractVersion across compatible implementation and catalog revisions. The release gate compares the candidate artifact with the published catalog and rejects removed capabilities or incompatible schemas, permissions, lifecycle and side effects. Optional inputs and ports may be added without republishing Pages; breaking changes require a distinct capability contract.
components/agent-ui exports the conversation surface, message, report, attachment, question and image presentation components. AgentConversationSurface binds a registered useData hook through ComponentAssembly host values. Page JSON supplies explicit layout, transcript, header, prompt, question, progress, interaction, artifact, preview, canvas and collection slots. The surface renders no default subtree. The host validates the opaque connection, authenticates the session, and supplies data hooks and command callbacks; Design renders their typed results. Frontend data hooks do not return JSX or visual renderer functions. Report and chat text share StreamingMarkdown, including managed resource access and image action ports. Image controls preserve original resource references when display bytes use temporary object URLs.
Conversation assembly capabilities are packaged in artifacts/conversation-capability-catalog.json under source monkeys.design.conversation.capabilities. Activate this additive catalog alongside the core catalog before publishing a Page that references these capabilities. The core catalog retains its existing identities and stays within the 512-entry artifact limit.
Canvas assembly capabilities are packaged separately in artifacts/canvas-capability-catalog.json under source monkeys.design.canvas.capabilities, so the reusable canvas surface can grow without exceeding the core catalog limit.
RecipeCanvasSkeleton is exported from @inf-monkeys-tech/monkeys-design/components/canvas, with its layout included in @inf-monkeys-tech/monkeys-design/styles.css. It displays horizontal canvas cards, a top toolbar and bottom zoom placeholders, adapting to one card in narrow panes. Hosts supply localized loading text through label and decide when to render it; document loading and persistence stay with the host. The component supports the shared animated and animation skeleton options.
发布
包名:@inf-monkeys-tech/monkeys-design。本仓库已经启用 GitHub Actions 自动发版,本地只负责提交代码、提升版本号和推送 tag;不需要在本地执行 npm publish,也不要提交 .npmrc 或 npm token。
自动发版规则:
- 推送 branch:不触发 npm 发布。
- 推送
vX.Y.Ztag:自动发布正式latest包。 - 发布认证通过 npm Trusted Publisher / GitHub Actions OIDC 完成,不依赖长期 npm token。
正式发布(latest)
维护者在 main 的干净工作区提升版本号,按发布范围选择 patch、minor 或 major,然后把分支和 tag 一起推到远端即可:
npm version patch
git push origin main --follow-tagsnpm version patch 会更新 package.json、生成版本提交,并创建对应的 vX.Y.Z tag。CI 只会在 vX.Y.Z tag 与 package.json 版本一致时发布正式包,并使用 latest dist-tag。
纯发版只在本地核对远端 main、版本、tag/npm 冲突和发布配置,不需要本地构建或完整测试,也不需要先触发 Validate。tag 流水线构建一次并保存产物及生成源码,随后在独立 runner 上并行执行类型、元数据、4 片测试、Readiness、样式、包内容和 Storybook 检查。全部检查成功后,发布任务下载同一份构建产物并发布 npm;检查和发布任务均不重新构建组件库。quality:check 检查已有的 dist,quality:publish 执行构建和检查。需要单独验证构建可复现性时,运行 yarn verify:reproducible;该命令不属于发布流水线。
如果要发布 minor 或 major 版本,将第一行改成:
npm version minor
# 或
npm version major包体积检查
构建产物的大小相对 scripts/package-size-budget.mjs 中记录的基线检查。根入口增长超过 8 KiB、整个包或压缩运行时代码增长超过 1% 时只输出警告;任一受检产物增长超过 30% 时阻止发布。Provider、Locale 和 Agent Workbench 子路径使用各自记录的警告阈值,同样以 30% 增长为阻止发布的阈值。
依赖外置和轻量入口内容检查独立执行:除 chroma-js 外,source map 中发现被打包的第三方依赖,或 Provider / Locale 入口包含落地页、内嵌图片等无关内容时,仍然阻止发布。警告不会自动更新基线。
npm Trusted Publisher
当前 npmjs 的 @inf-monkeys-tech/monkeys-design 包已经配置 Trusted Publisher/OIDC,绑定:
- Repository:
inf-monkeys/monkeys-design - Workflow filename:
npm-publish.yml(npm 表单只填文件名;文件位于.github/workflows/npm-publish.yml)
Trusted Publisher 配好后,CI 可以通过 OIDC 发布包,不需要在本地或仓库中保存 npm token。 由于当前 GitHub 仓库是 private,workflow 会显式关闭 npm provenance;Trusted Publishing/OIDC 仍然生效。
Platform UI palette
For optional platform UI colors, chart colors and shared UI/WebGL theme scopes, see Platform palette. The default preset is preserved. For opt-in platform borders, radii, shadows and typography, see Platform presentation.
Media action presentation
The declarative MediaViewer separates content format from record classification. Its kind supports image, pdf, video, audio, text, and file; the existing image/PDF defaults are unchanged. Video/audio use native playback controls, text is displayed as escaped plain text with an optional source.text value or a cancellable 256 KiB URL read, and file content retains the shared details/actions shell without claiming a specialized preview. source.posterUrl supplies a safe optional cover. A workflow output containing an image therefore uses the same image viewer and configurable toolbar as an imported image, while its generation information remains a separate declarative detail slot.
Gallery and CardGrid can read persisted boolean action states from each item with rowActionStatePath (for example ['context', 'actionStates']). rowActionActiveAppearance configures tone (primary, success, warning), icon fill and accessible label by action ID. rowActionStateOverrides accepts item-ID/action-ID booleans from confirmed command results; it takes precedence over queried states without replacing loaded items. These controls emit interaction intents; the consuming application owns state changes and persistence.
Media overlay buttons and the image viewer action/zoom bars share a frosted surface. CSS component tokens --monkeys-component-media-action-blur, -opacity, -hover-opacity, -border-opacity, -active-opacity, -active-hover-opacity and -active-border-opacity control its presentation (all suffixes use the same --monkeys-component-media-action prefix). Defaults are 8px blur, .35/.5 normal/hover opacity and .2/.3 active opacity. Media foreground/overlay colors inherit the theme. Warning foreground/surface colors are separately configurable. monkeys-media-fill-active-icon is an explicit opt-in for filled active icons on standalone buttons. Reduced-transparency preference disables blur and increases the surface opacity.
The same surface also consumes -border-width (dimension, default 1px), -border-style (strokeStyle, solid), -border-color (color), -radius (dimension, 999px), -foreground (color), -background (color), -hover-background (color), and -shadow (shadow). -size (dimension) controls icon buttons in both separate and grouped viewer toolbars; without an override they retain their respective 36px/32px defaults. Gallery overlay buttons share the border, radius, colors and shadow while retaining their declared size. Omitted color/shadow tokens retain the frosted semantic-media defaults above; active warning/success appearances and reduced-transparency preferences remain distinct states.
These are ordinary DTCG ThemeTokens, compiled through the existing theme provider rather than repeated in Page button declarations. For example, component.media-action.border-width becomes --monkeys-component-media-action-border-width; aliases can point to the project's existing seed/semantic tokens:
{
"component": {
"media-action": {
"border-width": { "$type": "dimension", "$value": { "value": 1, "unit": "px" } },
"radius": { "$type": "dimension", "$value": { "value": 999, "unit": "px" } },
"size": { "$type": "dimension", "$value": { "value": 2.25, "unit": "rem" } }
}
}
}Typography tokens
Tailwind hosts should spread typographyTailwindTheme from the theme-system entry after their legacy theme. Library and host utilities then consume the same Design Tokens:
| Token path | Type | Use |
| --- | --- | --- |
| semantic.font.body | fontFamily | Existing system body font |
| semantic.font.mono, semantic.font.serif | fontFamily | Code and serif text |
| semantic.font.size.{xs,sm,base,lg,xl,2xl…9xl} | dimension (px/rem) | Shared type scale |
| semantic.font.lineHeight.{xs,sm,base,lg,xl,2xl…9xl} | dimension or number | Line height for each size |
| semantic.font.weight.{normal,medium,semibold,bold,…} | fontWeight | Standard weight roles |
Old documents without size tokens keep the existing scale. For example, semantic.font.size.sm can be configured as { "$type": "dimension", "$value": { "value": 14, "unit": "px" } }. Use sm for controls/navigation/table content, xs for secondary text, and larger roles for metrics. Table headers use the body family; only code and credentials use monospace. Canvas renderers can use resolveTypographyTokens(theme, rootFontSize) to resolve the same px/rem values. Update both the applied CSS variables and provider theme when switching the token document.
Media action placement
Canvas image viewers can reserve a footer with canvasToolbar.actionsPlacement: "footer", so action buttons remain outside the fitted image and its pan/zoom surface. The default "overlay" retains existing floating actions. canvasToolbar.downloadPosition accepts "first" or "last" (default); both placements retain actionsGrouping, the shared media-action tokens and the declared action slot. An empty, export-disabled footer reserves no space.
Spatial relationships
RelationshipGraph3D is exported from components/visualizations and registered as monkeys.design.component.RelationshipGraph3D. Supply nodes (id, label, optional group, color, size, position) and edges (sourceId, targetId, optional weight, color, label). The component never infers relationships from spatial proximity. onNodeSelect returns the original caller-owned node; navigation stays with the consumer.
config controls clustered, spherical or caller-provided layouts; camera framing, pan, zoom and reduced-motion-aware rotation; node glow, group colors, edge emphasis; label density and collision spacing; and control labels/placement. interaction.enabled: false disables activation; openOn: "double-click" still supports Enter/Space. controls.visible and labels.visible are independent. No 2D/3D mode picker is embedded. See stories/workbench/RelationshipGraph3D.stories.tsx for the supported combinations.
Three.js loads lazily. Idle views stop drawing; damping, resize, hover, selection and camera operations invalidate the frame. Unmount or context loss releases observers, listeners, frames and WebGL resources. Missing WebGL reports onUnavailable, displays an error and retains keyboard-operable node labels rather than silently substituting a 2D graph. Controlled renderer tests do not establish real GPU performance or target-browser visual acceptance.
