Skip to content

样式规范

Jump to bottom
sunsonliu edited this page Jul 6, 2025 · 2 revisions

注：本规范在V0.9.5版本后生效

本规范由 Seeridia 设计并实现

原则

  1. 提升代码质量、可维护性和可读性。
  2. 保证界面样式规范
  3. 方便用户或开发者后续的维护和扩展。

文件结构

src/sass/
├── variables/            # CSS 变量定义目录
│   ├── base.scss         # 一级 CSS 变量（基础层：效果变量）
│   ├── semantic.scss     # 二级 CSS 变量（语义层：界面变量）
│   ├── open-color.scss   # Open Color 配色方案变量
│   └── index.scss        # 变量导出文件
├── themes/               # 主题定义目录
│   ├── default.scss      # 默认主题
│   ├── dark.scss         # 暗黑主题
│   ├── light.scss        # 明亮主题
│   └── ...               # 其他主题
├── components/           # 组件样式
├── markdown.scss         # Markdown 样式
├── cherry.scss           # 主样式文件
└── ...

变量分层定义

1 基础层常量 (variables/base.scss)

用途： 定义基础设计令牌

包含内容：

  • 尺寸系统：--spacing-*、--radius-*、--shadow-*
  • 字体系统：--font-*、--line-height-*
  • 其他基础令牌：--border-width-*、--opacity-*、--z-index-*

示例：

# variables/base.scss

:root {
  /* 间距系统 */
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --spacing-md: 12px;
  --spacing-lg: 16px;
  --spacing-xl: 24px;
  
  /* 字体系统 */
  --font-size-xs: 12px;
  --font-size-sm: 14px;
  --font-size-md: 16px;
  
  /* 圆角系统 */
  --radius-sm: 2px;
  --radius-md: 3px;
  --radius-lg: 6px;
  
  /* 阴影系统 */
  --shadow-md: 0 0 10px rgba(128, 145, 165, 0.2);
  
  /* 毛玻璃效果 */
  --glass-bg-white: rgba(255, 255, 255, 0.8);
  --blur-md: 8px;
}

2 语义层变量 (variables/semantic.scss)

用途： 将基础变量映射为具有业务语义的变量

分类规范：

  • --base-*：全局基础样式（字体颜色、边框、背景等）
  • --toolbar-*：工具栏相关
  • --editor-*：编辑器相关
  • --md-*：Markdown 元素相关
  • --dropdown-*、--bubble-*、--sidebar-*：各UI组件相关

示例：

# variables/semantic.scss

.cherry {
  /* 基础色彩 */
  --primary-color: #3582fb;
  --secondary-color: #f0f4ff;
  --base-font-color: #3f4a56;
  
  /* 工具栏 */
  --toolbar-bg: var(--oc-white);
  --toolbar-btn-color: #3f4a56;
  --toolbar-btn-hover-bg: #ebf3ff;
  
  /* 编辑器 */
  --editor-cursor-color: var(--primary-color);
  --editor-selection-bg: var(--oc-blue-1);
  
  /* Markdown 元素 */
  --md-heading-color: var(--base-font-color);
  --md-link-color: var(--oc-blue-6);
}

3 应用层 (主题样式文件)

  • 每个主题文件都继承了 base.scss 和 semantic.scss 中的变量定义，在顶部通过覆盖的方式进行主题色彩的调整
  • 而每个主题自己定义的样式则以规则的方式放在下面进行组织

示例：

# themes/green.scss

.cherry.theme__green {
  /* ========== 基础色彩变量覆盖 ========== */
  --primary-color: var(--oc-green-9);
  --secondary-color: var(--oc-green-0);

  --base-font-color: var(--primary-color);
  ···

  /* ========== 工具栏相关变量 ========== */
  --toolbar-bg: var(--oc-white);
  ···

  /* ========== 编辑器相关变量 ========== */
  --editor-header-color: var(--oc-green-7);
  ···

  /* ========== Markdown 相关变量 ========== */
  --md-heading-color: var(--oc-green-7);
  ···
}

/** 预览区域样式 */
.cherry-markdown.theme__green {
  h1,
  h2,
  h3,
  h4,
  h5 {
    text-align: center;
    margin-bottom: 35px;
  }

  /** 目录 */
  .toc {
    border-bottom: 1px solid var(--md-hr-border);
    padding-bottom: 15px;
    margin-bottom: 30px;

    .toc-title {
      text-align: center;
      padding-bottom: 15px;
      margin-top: 30px;
      margin-bottom: 15px;
      border-bottom: 1px solid var(--md-hr-border);
    }
  }
}

应用层变量使用规则

第一优先级：语义变量（高频定制）

/* 主题相关、用户经常定制的属性 */
.cherry-toolbar {
  background: var(--toolbar-bg-light);           // 主题色彩
  color: var(--toolbar-btn-color-light);         // 文字颜色
}

.cherry-markdown h1 {
  color: var(--md-heading-color);                // 标题颜色
  font-weight: var(--md-heading-font-weight);    // 标题字重
}

第二优先级：基础常量（中频使用）

/* 布局相关、标准尺寸 */
.some-component {
  margin: var(--spacing-md);                     // 标准间距
  border-radius: var(--radius-md);               // 标准圆角
  font-size: var(--font-size-sm);                // 标准字号
  box-shadow: var(--shadow-sm);                  // 标准阴影
}

第三优先级：硬编码（低频特殊）

/* 特殊场景、固定值、浏览器兼容 */
.special-component {
  -webkit-line-clamp: 3;                         // 浏览器特定
  z-index: 999999;                               // 特殊层级
  transition: transform 150ms cubic-bezier(0.4, 0, 0.2, 1); // 特殊动画
}

注意事项

允许的操作：

/* 重写基础色彩映射 */
--base-font-color: #new-color;
--base-editor-bg: var(--oc-gray-0);

/* 重写组件语义变量 */
--toolbar-bg-light: var(--oc-blue-1);
--md-link-color: var(--oc-red-6);

/* 使用基础层常量映射 */
--editor-header-color: var(--oc-violet-6);

禁止的操作：

/* 禁止：自定义新变量 */
--my-custom-color: #123456;
--special-background: rgba(0,0,0,0.5);
// 如有需要，请直接在规则中使用硬编码值，或增加语义层变量

/* 禁止：重写基础层常量 */
--oc-blue-6: #custom-blue;
--spacing-md: 20px;
// 如有需要，请直接增加基础层变量

Clone this wiki locally