样式与主题

X-Next 的样式由 src/packages/index.scss 汇总。发布后，用户通过下面的方式引入完整样式：

import 'x-next/dist/style.css';

类名前缀

组件样式默认使用 x 前缀，例如按钮组件的基础类名为 x-button。

文档站样式

文档站在 .vitepress/theme/index.ts 中引入源码样式：

import '../../../packages/index.scss';

这样可以在编写文档时直接渲染当前源码组件，适合组件开发和文档联调。

主题 Token 分层

X-Next 后续自定义主题系统以 CSS 变量作为底层协议。当前按三层组织：

1. Seed token：基础色、尺寸、圆角、字体、阴影、动效，例如 --x-color-primary、--x-size-medium、--x-border-radius-medium。
2. Semantic token：语义化颜色和状态，例如 --x-color-text-primary、--x-color-bg-surface、--x-color-border-default、--x-color-danger-subtle。
3. Component alias token：组件级默认值，例如后续 Button 会使用 --x-button-color-bg-default、--x-button-color-text-danger 这类变量。

组件样式应优先消费 semantic token 或 component alias token，不应在组件根类里重新定义用户期望从祖先节点覆盖的 public token。

当前语义 Token

文本：

Token	用途
--x-color-text-primary	主要文本
--x-color-text-secondary	次级文本
--x-color-text-tertiary	辅助文本、占位提示
--x-color-text-disabled	禁用文本

背景：

Token	用途
--x-color-bg-page	页面背景
--x-color-bg-surface	卡片、输入框、弹层内容背景
--x-color-bg-subtle	弱背景、浅填充
--x-color-bg-elevated	弹层背景

边框：

Token	用途
--x-color-border-default	默认边框
--x-color-border-subtle	弱边框、分割线
--x-color-border-focus	聚焦边框

状态色：

Token	用途
--x-color-primary-subtle / --x-color-primary-solid	主色弱背景 / 实色
--x-color-success-subtle / --x-color-success-solid	成功弱背景 / 实色
--x-color-warning-subtle / --x-color-warning-solid	警告弱背景 / 实色
--x-color-danger-subtle / --x-color-danger-solid	危险弱背景 / 实色
--x-color-strong-subtle / --x-color-strong-solid	强提醒弱背景 / 实色

表单输入：

Token	用途
--x-field-color-bg / --x-field-color-bg-hover / --x-field-color-bg-focus	输入框、选择器、日期选择器的默认 / 悬浮 / 聚焦背景
--x-field-color-bg-disabled	禁用背景
--x-field-color-text / --x-field-color-placeholder / --x-field-color-text-disabled	输入文本、占位符、禁用文本
--x-field-color-border / --x-field-color-border-hover / --x-field-color-border-focus	默认 / 悬浮 / 聚焦边框
--x-field-color-border-error	错误态边框
--x-field-status-success-* / --x-field-status-warning-* / --x-field-status-error-* / --x-field-status-validating-*	Form 校验状态下的背景、边框、阴影、提示文字和图标

覆盖示例

全局覆盖：

:root {
  --x-color-primary: rgb(22 93 255 / 100%);
  --x-color-border-focus: var(--x-color-primary-6);
}

局部主题容器覆盖：

<template>
  <section class="brand-scope">
    <x-button status="danger">删除</x-button>
    <x-input placeholder="局部主题" />
  </section>
</template>

<style>
.brand-scope {
  --x-color-primary: rgb(15 118 110 / 100%);
  --x-color-border-focus: var(--x-color-primary);
  --x-field-color-border-focus: var(--x-color-primary);
  --x-field-status-error-border-focus: rgb(220 38 38 / 100%);
}
</style>

后续 ConfigProvider 应基于同一套 CSS 变量协议实现，本质上也是向祖先节点写入这些 token。

文档站样式约束

文档站 demo 样式只负责布局，不应直接修补组件内部结构。优先使用 demo 专用类：

<div class="example-box">
  <x-input class="demo-field" />
</div>

.demo-field {
  width: 320px;
  max-width: 100%;
}

不要在文档主题里新增 .example-box .x-input--wrapper、.example-box .x-table--td 这类规则。若必须临时保留，需要在样式体系审查或对应组件 BUG 审查中记录原因。

样式检查

项目提供样式检查脚本，先用于本地审查和改造过程中的回归检查：

pnpm run check:style-tokens
pnpm run check:style-colors
pnpm run check:doc-style

• check:style-tokens：扫描 var(--x-*) 引用是否有定义。
• check:style-colors：扫描组件和文档主题中的硬编码颜色。
• check:doc-style：扫描文档主题是否直接命中组件内部结构类。

后续建议

建议逐步补充：

• 组件尺寸规范
• 暗色模式策略
• 按需样式加载方式