CSS API 参考

CSS API 参考覆盖 pantoken 的基于类的组件层：构建在代币系统之上的组件、工具类、全局规则和声明。

组件

名称	类	摘要
agent-shell	.instui-agent-shell	用于 AI 代理的表面容器。
alert	.instui-alert	带有状态彩色条和来自共享图标集的掩码状态图形的内联消息。
avatar	.instui-avatar	显示首字母或图像的用户头像，默认为圆形。
badge	.instui-badge	放置在目标角落上的小计数或状态点。
banner	.instui-banner	可关闭的、有图标的消息表面，用于页面级或上下文内的公告。
billboard	.instui-billboard	大型空状态或号召性用块：主图标或图像、标题和消息。
breadcrumb	.instui-breadcrumb	带分隔符的面包屑路径；最后一个面包屑为当前页面。
breadcrumb.link	li	一个面包屑（InstUI Breadcrumb.Link），父项的 <ol> 中的 <li>；最后一个是当前页面。
button	.instui-button	可访问的操作控件，使用代币调色板样式；默认为主要样式。
byline	.instui-byline	媒体对象：标题和描述旁的主图像。
calendar	.instui-calendar	带导航、星期标题和日期单元的静态月份网格。
calendar.day	.day	一个日期单元（InstUI Calendar.Day）；-today, -selected 和 -outside-month 标记其状态。
card	.instui-card	接受任意内容的表面容器。
checkbox	.instui-checkbox	原生复选框及其标签，或通过 -variant-toggle 切换为开关。
close-button	.instui-close-button	透明图标按钮，自绘 × 符号，提供三种尺寸及一种带色背景的变体。
context-view	.instui-context-view	带有尖角且可定位在任一侧的提升提示；可作为原生 [popover] 使用。
drawer-layout	.instui-drawer-layout	带可折叠侧盘和主可滚动内容窗格的分割布局。
drawer-layout.content	.content	填充侧盘旁剩余空间的主内容窗格。
drawer-layout.tray	.tray	主内容旁的侧面板，带可选覆盖和托盘式表面修饰符。
file-drop	.instui-file-drop	具有悬停、接受和拒绝状态的文件拖放区。
form-field	.instui-form-field	表单字段包装器：标签、其控件以及内联、必填或只读布局。
form-field-group	.instui-form-field-group	带标题的 <fieldset> 组，提供列或内联布局和可配置间距。
form-field-messages	.instui-form-field-messages	字段帮助和校验消息 — 提示、错误、成功和仅供屏幕阅读器使用；错误和成功带图标。
heading	.instui-heading	标题排版，从 -level-h1 到 -level-h6。
img	.instui-img	带有显示、裁剪和效果修饰符并可堆叠的样式化 <img>。
in-place-edit	.instui-in-place-edit	一个 [contenteditable]，在获得焦点前以文本形式呈现，获焦后显示输入外壳。
input-group	.instui-input-group	围绕文本输入的外观封装，带有前导和尾随图标插槽。
link	.instui-link	带有尺寸、用于深色背景的反色变体，以及内联或无样式形式的样式化超链接。
list	.instui-list	具有代币驱动条目间距的列表。
list.item	.instui-list	列表项（InstUI List.Item）。
mask	.instui-mask	填满其定位父元素并居中内容的内流覆盖——例如卡片上的加载指示器。对于模态，优先使用原生 <dialog>（其 ::backdrop 是遮罩）。这些修饰符的每一种也可全局使用（裸用或链式附加到任意组件）——参见 mask 全局工具。
menu	.instui-menu	包含条目、组和分隔符的下拉表面。
menu.group	.group	带标签的组标题（InstUI Menu.Group/Menu.ItemGroup）。
menu.item	.item	菜单项（InstUI Menu.Item）；可添加 -disabled、-highlighted 或 -active/[aria-checked]。
menu.separator	.separator	条目之间的分割线（InstUI Menu.Separator）。
metric	.instui-metric	带标签的统计信息 — 大数值上方的说明文字。
modal	.instui-modal	对话框表面（可在原生 <dialog> 上工作）；包含头部/主体/页脚部分。
modal.body	.body	内容区域（InstUI Modal.Body）；孤立的 <img> 可全幅延伸。
modal.footer	.footer	操作行（InstUI Modal.Footer）。
modal.header	.header	标题行（InstUI Modal.Header）。
number-input	.instui-number-input	带有 +/- 微调列的数字输入外观。
pagination	.instui-pagination	分页导航：编号页、第一页、上一页、下一页和最后一页箭头，以及表示间隙的省略号。
pagination.page	.page	页面链接或按钮（InstUI Pagination.Page）；当前页面带有 [aria-current]。
pill	.instui-pill	紧凑的状态标签；可使用共享的 -icon-<name> 形式添加前导图标。
popover	.instui-popover	用于原生 [popover] 的提升表面，使用 CSS 锚点定位。
progress	.instui-progress	带彩色进度计、尺寸和可选数值标签的确定性进度条。
progress-circle	.instui-progress-circle	由 --value 和 --value-max 自定义属性驱动的圆形进度环。
radio	.instui-radio	原生单选按钮及其标签。
radio-input-group	.instui-radio-input-group	单选组 <fieldset>，可为普通形式或连接的分段切换样式。
range-input	.instui-range-input	带样式的范围滑块，带有反色数值气泡。
rating	.instui-rating	带有填充和空心图形以及可选数字标签的星级评分。
side-nav-bar	.instui-side-nav-bar	一列图标在标签上方的垂直导航栏，带有最小化的仅图标模式。
side-nav-bar.item	.item	一个导航条目（InstUI SideNavBar.Item）；使用 -selected 标记激活项。
simple-select	.instui-simple-select	带有下拉箭头的本机样式化 <select>，匹配文本输入的状态和尺寸。
spinner	.instui-spinner	一个动画加载环；请为其提供 role="status" 和 aria-label。
table	.instui-table	用于 th 与 td 的样式化数据表，并可选带标题，支持悬停、固定和堆栈卡片布局。
table.body	tbody	表的数据行组（InstUI Table.Body）。
table.cell	td	数据单元格（InstUI Table.Cell）。
table.col-header	th	列头单元格（InstUI Table.ColHeader）；默认的 th 样式会被用于 th[scope="row"] 的 table.row-header 覆盖。
table.head	thead	表的头部行组（InstUI Table.Head）。
table.row	tr	一行表格（InstUI Table.Row）。
table.row-header	th[scope="row"]	行头单元格（InstUI Table.RowHeader）；样式来自行头令牌，而非列头令牌。
tabs	.instui-tabs	标签面板集合：标签列表、可选标签及其面板。
tabs.panel	.panel	标签的内容面板（InstUI Tabs.Panel）。
tabs.tab	.tab	单个标签按钮（InstUI Tabs.Tab，由父级 Tabs 的标签列表配置）；使用 -selected 标记激活项。
tag	.instui-tag	用于关键字或筛选的内联芯片。
text	.instui-text	正文文本排版，带有尺寸、字重、颜色和样式修饰符。
text-area	.instui-text-area	样式化且可调整大小的本机 <textarea>，具有与文本输入相同的状态和尺寸。
text-input	.instui-text-input	样式化的本机 <input> —— 包括 date, time 和 datetime-local，由浏览器提供选择器 —— 带有验证状态和尺寸。
toggle-details	.instui-toggle-details	带有旋转箭头的样式化本机 <details> 折叠控件。
toggle-group	.instui-toggle-group	基于 <details> 的有边框折叠控件：带箭头的摘要行和可折叠内容。
tooltip	.instui-tooltip	一个可定位在任意一侧的 CSS 悬停与焦点提示气泡。
tray	.instui-tray	从任意一侧滑入的边缘固定面板；一个本机 [popover] 或 <dialog>。
tree-browser	.instui-tree-browser	带有旋转箭头的嵌套集合与叶项的折叠树结构。
view	.instui-view	View 原语：一个中性盒子，具有用于背景、边框、圆角、阴影、显示、定位、溢出和光标的键值修饰符。这些修饰符中的每一个也可全局使用（裸用或链式附加到任何其他组件）——参见 background/border/shadow/display/position/overflow/cursor 工具。

实用工具

名称	类	摘要
color	.--text-danger	语义颜色工具：.--bg-<name>、.--text-<name>（别名为 .--color-<name>）和 .--border-<name>，用于策划的语义调色板。每个也都有组件附加的别名修饰符（例如在任何 .instui-<component> 上使用的 -bg-danger）。
cursor	.--cursor-pointer	cursor 作为可组合的全局类 — .--cursor-<value> — 可裸用或链式附加到任何组件（.instui-button.--cursor-pointer）。
gap	.--gap-md	基于间距刻度的 Flex/网格 gap 工具，短写（--gap-sm）或长写（--gap-small）。可裸用或链式附加到任何组件（.instui-view.--gap-sm）——已经由组件特定令牌设置其自身 gap 的组件可能会被覆盖。
icon	.instui-icon	图标系统：.instui-icon 尺寸以及在任何元素之前用作遮罩图形的共享 -icon-<name> 绘制器（位于 currentColor 中）。
layout	.--display-flex	显示与文本对齐工具 — .--display-<value> 与 .--text-align-<value> — 作为可组合的全局类，可裸用或链式附加到任何组件。
maskglobal	.--mask-overlay	mask 组件覆盖修饰符的全局双份副本 — --mask-overlay, --mask-fullscreen, --mask-blur — 可裸用或链式附加到任何组件，无需包裹在 .instui-mask 元素中。
overflow	.--overflow-x-hidden	overflow-x/overflow-y 作为可组合的全局类 — .--overflow-x-<value> / .--overflow-y-<value> — 可裸用或链式附加到任何组件。
position	.--position-relative	position 作为可组合的全局类 — .--position-<value> — 可裸用或链式附加到任何组件（.instui-button.--position-relative）。
responsive	[class*="-hidden-"],[class*="-show-"]	基于主题断点刻度的视窗或容器宽度显示/隐藏类。
screen-reader-content	.instui-screen-reader-content	视觉上隐藏内容同时保持其对辅助技术可用（标准裁剪模式）。
spacing	.--p-md	外边距和内边距工具 —— .--m<side>-<step> / .--margin-<side>-<step> 和 .--p<side>-<step> / .--padding-<side>-<step>，基于间距刻度（边侧 t/b/s/e/x/y 或无，支持短写或完整写法 —— 例如 --mb-sm 与 --margin-bottom-small 是相同规则；margin 还接受 auto）。可单独使用或链式添加到任意组件（例如 class="instui-view --mb-sm"）。
stacking	.--stack-topmost	z-index 深度工具 —— .--stack-<level>（deepest, below, above, topmost）—— 可单独使用或链式添加到任意组件，使图层按可预测方式堆叠，而不是手动调整数字。
transition	.instui-transition.-transition-fade-entering	用于 Transition 组件的动画状态类 —— .instui-transition 与状态类（-transition-fade-entering, -transition-scale-exited, 等）—— 可单独使用或链式添加到任意组件。
truncate	.--truncate	带有行数限制的省略号截断，由 --lines 控制 —— 可单独使用或链式添加到任意组件（.instui-button.--truncate）。
visual-debug	.-with-visual-debug	布局调试轮廓：将复合 .-with-visual-debug 添加到任意元素以描绘该盒子及其直接子元素，便于一目了然地查看布局结构。

规则

名称	类	摘要
base	*	可选的全局重置：box-sizing、页面表面、基础文本颜色和字体、color-scheme 以及链接默认样式。
prose	:where(body)	用于原生 HTML 的排版默认值 —— 标题、段落、列表、链接和代码 —— 在导入处自动应用（默认 :where(body)）；传入 options.scope 可定位到不同的内容根（例如 .vp-doc）。

Plugins

名称	类	摘要
logos	.logos	Instructure 产品徽标作为 CSS 图像 token：--instui-logo-<product>-<layout>-<mode> 包含 data-URI SVG，因此徽标可通过例如 background-image: var(--instui-logo-canvas-horizontal-color) 呈现。
primitives	.instui-bg-primitive-color-white	原始基础色板的可选工具类：.instui-bg-/fg-/border-primitive-color-<name> 可使用基础颜色 token 上色，另外有 font-family/font-weight 用于基础字体 token。为了保持语义工具的纯粹覆盖，这些类被排除在语义工具之外。
visual-debug	.-with-visual-debug	布局调试轮廓：将复合 .-with-visual-debug 添加到任意元素以描绘该盒子及其直接子元素，便于一目了然地查看布局结构。

layout

名称	类	摘要
callout	div[class~="instui-callout"]	用于简短提醒或注释的内联信息提示。
hero	div[class~="instui-hero"]	全宽页眉区，包含标题、副标题和可选背景图片。
page-layout	div[class~="instui-page-layout"]	标准三栏页面布局，包含页眉、侧边栏和主内容区域。
rubric-note	div[class~="instui-rubric-note"]	带有评分类别和评分指示器的结构化笔记。
testimonial	div[class~="instui-testimonial"]	带有署名和可选图像的引用或推荐展示。
two-column	div[class~="instui-two-column"]	左右两栏布局，包含左侧和右侧内容区域。
wrapper	body[class~="instui-display-flex"]	应用外壳行：侧边导航、带页眉的容器，以及可选面板。