From 75c12681045db0b647099bc7e33b1308b943d873 Mon Sep 17 00:00:00 2001 From: dufu1991 Date: Fri, 3 Nov 2023 15:40:09 +0800 Subject: [PATCH] [doc]v0.4.0 --- doc/components/avatar/api.md | 20 ++ doc/components/avatar/api_en.md | 20 ++ doc/components/avatar/guide.md | 8 + doc/components/avatar/guide_en.md | 8 + doc/components/avatar/version.md | 5 + doc/components/avatar/version_en.md | 5 + doc/components/icon/guide.md | 3 +- doc/components/icon/guide_en.md | 3 +- doc/guide/changelog.md | 6 + doc/guide/changelog_en.md | 6 + doc/guide/future.md | 2 +- doc/guide/future_en.md | 2 +- doc/guide/icon.md | 3 +- doc/guide/icon_en.md | 3 +- doc/guide/internation.md | 2 +- doc/guide/internation_en.md | 2 +- doc/guide/milestone.md | 4 + doc/guide/milestone_en.md | 4 + doc/guide/quickStart.md | 82 +++++--- doc/guide/quickStart_en.md | 92 +++++---- doc/guide/theme.md | 273 +++++++++++++++++++++++---- doc/guide/theme_en.md | 277 ++++++++++++++++++++++++---- 22 files changed, 692 insertions(+), 138 deletions(-) diff --git a/doc/components/avatar/api.md b/doc/components/avatar/api.md index bbb25c9e..0389e51a 100644 --- a/doc/components/avatar/api.md +++ b/doc/components/avatar/api.md @@ -17,3 +17,23 @@ | 名称 | 参数 | 描述 | | ----- | ---- | ---------- | | click | - | 点击触发。 | + +## Avatars Props + +| 属性 | 类型 | 默认值 | 可选值 | 必传 | 说明 | +| --------- | ------- | ------ | ------------------------------------- | ---- | -------------------------------- | +| data | Array | [] | - | N | 由 Avatar Props 组成的头像数据。 | +| radius | String | 'full' | 'none'/'base'/'xl'/'2xl'/'3xl'/'full' | N | 圆角风格。 | +| size | String | 'md' | 'xs'/'sm'/'base'/'md'/'lg'/'xl' | N | 头像框大小。 | +| compact | Number | 5 | 1-10 | N | 紧凑程度，越大越紧凑。 | +| lineWidth | String | 3 | '0'/'1'/'2'/'3'/'4'/'8' | N | 边框粗细。 | +| reverse | Boolean | false | true/false | N | 是否反向。 | +| max | Number | 10 | - | N | 最大最大显示数量。 | +| top | String | 0 | 'totle'/'add'/'none'/Slot | N | 顶层内容。 | +| injClass | String | '' | Class | N | 注入 CSS 名称。 | + +## Avatars Events + +| 名称 | 参数 | 描述 | +| ---------- | ---- | ---------------- | +| clickgroup | - | 点击头像组触发。 | diff --git a/doc/components/avatar/api_en.md b/doc/components/avatar/api_en.md index abcc48fc..e9beed4e 100644 --- a/doc/components/avatar/api_en.md +++ b/doc/components/avatar/api_en.md @@ -17,3 +17,23 @@ | Name | Parameter | Description | | ----- | --------- | ----------------- | | click | - | Click to trigger. | + +## Avatars Props + +| Properties | Type | Default value | Optional value | required | Description | +| ---------- | ------- | ------------- | ------------------------------------- | -------- | ----------------------------------------- | +| data | Array | [] | - | N | The avatar data composed of Avatar Props. | +| radius | String | 'full' | 'none'/'base'/'xl'/'2xl'/'3xl'/'full' | N | Round -corner style. | +| size | String | 'md' | 'xs'/'sm'/'base'/'md'/'lg'/'xl' | N | The size of the avatar box. | +| compact | Number | 5 | 1-10 | N | Compactness, the larger the more compact. | +| lineWidth | String | 3 | '0'/'1'/'2'/'3'/'4'/'8' | N | Border thickness. | +| reverse | Boolean | false | true/false | N | Whether to reverse. | +| max | Number | 10 | - | N | Maximum maximum display quantity. | +| top | String | 0 | 'totle'/'add'/'none'/Slot | N | Top content. | +| injClass | String | '' | Class | N | Inject the CSS name. | + +## Avatars Events + +| Name | Parameter | Description | +| ---------- | --------- | ------------------------------ | +| clickgroup | - | Click avatar group to trigger. | diff --git a/doc/components/avatar/guide.md b/doc/components/avatar/guide.md index 1d05148d..dc8afaf1 100644 --- a/doc/components/avatar/guide.md +++ b/doc/components/avatar/guide.md @@ -17,3 +17,11 @@ image > alt > icon。 通过 injClass 参数可以向组件内部 button 元素注入 CSS 名称（不仅限于 Tailwind CSS），这将使组件样式有更多自定义可能性，示例中通过 injClass 实现了自定义背景色和边框颜色。 若注入的 class 没生效，请在注入的 class 名称前添加“!” ，可参考 [Tailwind Important modifier](https://tailwindcss.com/docs/configuration#important-modifier)。 + +## 头像组 + +v0.4.0 开始支持头像组，头像组的使用场景是在头像框内部显示多个头像，例如群聊头像、评论头像等。传入由 Avatar Props 组成的数组即可，头像组有自己的 Props 用于控制不同样式。 + +默认顶层显示头像总数，可通过 top 参数控制顶层显示内容，可选值有 totle（显示头像总数）、add（新增头像 Icon）、none（不显示）、Slot（自定义顶层内容）。 + +头像组 Props 自己也有一个 injClass，可为头像组注入 Class 名称，一般用于当默认边框颜色与背景色不统一时传入传入 ring 的颜色使其统一。 diff --git a/doc/components/avatar/guide_en.md b/doc/components/avatar/guide_en.md index ddcb564e..d14b0112 100644 --- a/doc/components/avatar/guide_en.md +++ b/doc/components/avatar/guide_en.md @@ -17,3 +17,11 @@ This parameter determines the proportion of the avatar frame that the image insi The `injClass` parameter can be used to inject custom CSS class names (not limited to Tailwind CSS) into the `button` element inside the component. This allows for further customization of the component's appearance, as demonstrated in the example using `injClass` to customize the background and border colors. If the injected class name does not take effect, add a `!` before the class name, as demonstrated in the [Tailwind Important Modifier](https://tailwindcss.com/docs/configuration#important-modifier). + +## Avatar Group + +Starting with v0.4.0, the `Avatar` component supports avatar groups, which can be used to display multiple avatars inside an avatar frame, such as group chat avatars, comment avatars, etc. Simply pass in an array of `Avatar Props` to use. The avatar group has its own props for controlling different styles. + +By default, the total number of avatars is displayed at the top level, and the `top` parameter can be used to control what is displayed at the top level, with the following optional values: `totle` (displays the total number of avatars), `add` (displays an icon for adding avatars), `none` (does not display anything), and `Slot` (allows for custom content at the top level). + +The avatar group props also have an `injClass` that can be used to insert a class name into the avatar group, which is generally used to unify the background and border colors when the default border color does not match the background color. Note that the `ring` color must be passed in. diff --git a/doc/components/avatar/version.md b/doc/components/avatar/version.md index e69de29b..96a2732b 100644 --- a/doc/components/avatar/version.md +++ b/doc/components/avatar/version.md @@ -0,0 +1,5 @@ +## 0.4.0 + +- [!tag|A|0|]新增头像组用法。 + +2023-11-03 diff --git a/doc/components/avatar/version_en.md b/doc/components/avatar/version_en.md index e69de29b..80eaffef 100644 --- a/doc/components/avatar/version_en.md +++ b/doc/components/avatar/version_en.md @@ -0,0 +1,5 @@ +## 0.4.0 + +- [!tag|A|0|] Add avatar component. + +2023-11-03 diff --git a/doc/components/icon/guide.md b/doc/components/icon/guide.md index 7aef24d9..a311f9ca 100644 --- a/doc/components/icon/guide.md +++ b/doc/components/icon/guide.md @@ -25,6 +25,7 @@ STDF 部分组件内使用的图标源自 [Remix Icon 图标库](https://remixic | 图标名称 | 所属组件 | | ----------------------------- | ---------------- | | ri-user-3-line | Avatar | +| ri-user-add-line | Avatars | | ri-arrow-right-s-line | Cell / NoticeBar | | ri-checkbox-fill | Checkbox | | ri-checkbox-line | Checkbox | @@ -49,8 +50,6 @@ STDF 部分组件内使用的图标源自 [Remix Icon 图标库](https://remixic | ri-error-warning-line | Toast | | ri-information-line | Toast | -可到 `node_modules/stdf/assets/fonts/stdf.remixicon.symbol.svg` 查看由这些图标组成的 SVG Sprites。 - 可到 `node_modules/stdf/assets/svg_base/` 查看这些图标的 SVG 源文件。 ## 图标名称 diff --git a/doc/components/icon/guide_en.md b/doc/components/icon/guide_en.md index 11fff8d1..e229a9ff 100644 --- a/doc/components/icon/guide_en.md +++ b/doc/components/icon/guide_en.md @@ -25,6 +25,7 @@ Here are the icons and their corresponding components: | Icon Name | Component | | ----------------------------- | ---------------- | | ri-user-3-line | Avatar | +| ri-user-add-line | Avatars | | ri-arrow-right-s-line | Cell / NoticeBar | | ri-checkbox-fill | Checkbox | | ri-checkbox-line | Checkbox | @@ -49,8 +50,6 @@ Here are the icons and their corresponding components: | ri-error-warning-line | Toast | | ri-information-line | Toast | -You can find the SVG Sprites composed of these icons in `node_modules/stdf/assets/fonts/stdf.remixicon.symbol.svg`. - You can find the SVG source files for these icons in `node_modules/stdf/assets/svg_base/`. ## Icon Name diff --git a/doc/guide/changelog.md b/doc/guide/changelog.md index ac9d6645..a5ae2828 100644 --- a/doc/guide/changelog.md +++ b/doc/guide/changelog.md @@ -1,3 +1,9 @@ +## 0.4.0 + +- 新增支持多主题配置，请参考 [主题配置](https://stdf.design/#/guide?nav=theme)、[色彩](https://stdf.design/#/guide?nav=color)、[主题生成器](https://stdf.design/#/guide?nav=generator)。 +- 按照 Tailwind 命名规则统一将灰色由 `gray5` 改为 `gray-500` 写法，请注意升级后更改写法。详见 [色彩](https://stdf.design/#/guide?nav=color)。 +- Avatar 组件新增头像组用法，详见 [Avatar](https://stdf.design/#/components?nav=avatar&tab=4)。 + ## 0.3.2 - 修复 Input 组件，详见 [Input](https://stdf.design/#/components?nav=input&tab=4)。 diff --git a/doc/guide/changelog_en.md b/doc/guide/changelog_en.md index 2bfa64ea..37a9bb8d 100644 --- a/doc/guide/changelog_en.md +++ b/doc/guide/changelog_en.md @@ -1,3 +1,9 @@ +## 0.4.0 + +- Added support for multi-theme configuration, please refer to [Theme Configuration](https://stdf.design/#/guide?nav=theme), [Color](https://stdf.design/#/guide?nav=color), [Theme Generator](https://stdf.design/#/guide?nav=generator). +- In accordance with the Tailwind naming rules, the gray color has been uniformly changed from `gray5` to `gray-500` writing method. Please note that the writing method should be changed after the upgrade. See [Color](https://stdf.design/#/guide?nav=color) for details. +- The Avatar component adds the usage of the avatar group, please see [Avatar](https://stdf.design/#/components?nav=avatar&tab=4). + ## 0.3.2 - Fix Input, please see [Input](https://stdf.design/#/components?nav=input&tab=4). diff --git a/doc/guide/future.md b/doc/guide/future.md index d34c8885..3d48b37f 100644 --- a/doc/guide/future.md +++ b/doc/guide/future.md @@ -1,6 +1,6 @@ ## 新增 💪 -- [ ] 按照 Tailwind CSS 变量规则，实现自定义主题色。 +- [x] 按照 Tailwind CSS 变量规则，实现自定义主题色。 - [ ] 新增 SecurityCode-安全码组件，一般用于输入短信或邮件收到的数字校验码。 - [x] 开发一款 Vite/Rollup 插件，支持将指定目录下的所有 svg 合并为 SVG symbol。 - [x] 开发一款 VS Code 插件，支持光标悬浮显示 STDF 组件 API 等功能。 diff --git a/doc/guide/future_en.md b/doc/guide/future_en.md index 4a1e6c5b..d8d29837 100644 --- a/doc/guide/future_en.md +++ b/doc/guide/future_en.md @@ -1,6 +1,6 @@ ## New Features 💪 -- [ ] Implement custom theme colors according to Tailwind CSS variable rules. +- [x] Implement custom theme colors according to Tailwind CSS variable rules. - [ ] Add SecurityCode component, which is generally used for entering numeric verification codes received via SMS or email. - [x] Develop a Vite/Rollup plugin that supports merging all SVGs in a specified directory into an SVG symbol. - [x] Develop a VS Code plugin that supports displaying STDF component API and other functions when hovering over the cursor. diff --git a/doc/guide/icon.md b/doc/guide/icon.md index f4d22c1a..9a37e1f1 100644 --- a/doc/guide/icon.md +++ b/doc/guide/icon.md @@ -25,6 +25,7 @@ STDF 部分组件内使用的图标源自 [Remix Icon 图标库](https://remixic | 图标名称 | 所属组件 | | ----------------------------- | ---------------- | | ri-user-3-line | Avatar | +| ri-user-add-line | Avatars | | ri-arrow-right-s-line | Cell / NoticeBar | | ri-checkbox-fill | Checkbox | | ri-checkbox-line | Checkbox | @@ -49,6 +50,4 @@ STDF 部分组件内使用的图标源自 [Remix Icon 图标库](https://remixic | ri-error-warning-line | Toast | | ri-information-line | Toast | -可到 `node_modules/stdf/assets/fonts/stdf.remixicon.symbol.svg` 查看由这些图标组成的 SVG Sprites。 - 可到 `node_modules/stdf/assets/svg_base/` 查看这些图标的 SVG 源文件。 diff --git a/doc/guide/icon_en.md b/doc/guide/icon_en.md index 913b619d..a0d730c6 100644 --- a/doc/guide/icon_en.md +++ b/doc/guide/icon_en.md @@ -25,6 +25,7 @@ Here are the icons and their corresponding components: | Icon Name | Component | | ----------------------------- | ---------------- | | ri-user-3-line | Avatar | +| ri-user-add-line | Avatars | | ri-arrow-right-s-line | Cell / NoticeBar | | ri-checkbox-fill | Checkbox | | ri-checkbox-line | Checkbox | @@ -49,6 +50,4 @@ Here are the icons and their corresponding components: | ri-error-warning-line | Toast | | ri-information-line | Toast | -You can find the SVG Sprites composed of these icons in `node_modules/stdf/assets/fonts/stdf.remixicon.symbol.svg`. - You can find the SVG source files for these icons in `node_modules/stdf/assets/svg_base/`. diff --git a/doc/guide/internation.md b/doc/guide/internation.md index afbd8460..ece8c497 100644 --- a/doc/guide/internation.md +++ b/doc/guide/internation.md @@ -87,7 +87,7 @@ STDF 组件使用 Svelte 的 [Context](https://svelte.dev/docs#run-time-svelte-s | 繁体中文（中国香港） | zh_HK | | 繁体中文（中国台湾） | zh_TW | -多语言文件由机器翻译，如果有不准确的地方，请提交 PR 进行修正。 +> 多语言文件由机器翻译，如果有不准确的地方，请提交 PR 进行修正。 ## 增加语言包 diff --git a/doc/guide/internation_en.md b/doc/guide/internation_en.md index c6a96d82..b551c4c3 100644 --- a/doc/guide/internation_en.md +++ b/doc/guide/internation_en.md @@ -87,7 +87,7 @@ Currently supported languages: | Traditional Chinese (China Hong Kong) | zh_HK | | Traditional Chinese (China Taiwan) | zh_TW | -The multilingual files are translated by machine. If there are any inaccuracies, please submit a PR for correction. +> The multilingual files are translated by machine. If there are any inaccuracies, please submit a PR for correction. ## Adding a Language Pack diff --git a/doc/guide/milestone.md b/doc/guide/milestone.md index a0280b87..70bcce7e 100644 --- a/doc/guide/milestone.md +++ b/doc/guide/milestone.md @@ -1,3 +1,7 @@ +## 2023-11-03 + +支持多主题配置 @0.4.0 。 + ## 2023-08-24 完成 STDF 配套的模板脚手架 [create-stdf](https://www.npmjs.com/package/create-stdf)，Vite/Rollup 插件 [rollup-plugin-stdf-icon](https://www.npmjs.com/package/rollup-plugin-stdf-icon)，VS Code 插件 [STDF for VS Code](https://marketplace.visualstudio.com/items?itemName=STDF.stdf-vscode-extension)。 diff --git a/doc/guide/milestone_en.md b/doc/guide/milestone_en.md index f97facd7..455dbfc4 100644 --- a/doc/guide/milestone_en.md +++ b/doc/guide/milestone_en.md @@ -1,3 +1,7 @@ +## 2023-11-03 + +Support multi-theme configuration @0.4.0. + ## 2023-08-24 Completed the template scaffolding tool [create-stdf](https://www.npmjs.com/package/create-stdf), Vite/Rollup plugin [rollup-plugin-stdf-icon](https://www.npmjs.com/package/rollup-plugin-stdf-icon), and VS Code plugin [STDF for VS Code](https://marketplace.visualstudio.com/items?itemName=STDF.stdf-vscode-extension) for STDF. diff --git a/doc/guide/quickStart.md b/doc/guide/quickStart.md index 4953bac4..b05da4de 100644 --- a/doc/guide/quickStart.md +++ b/doc/guide/quickStart.md @@ -68,43 +68,73 @@ npx tailwindcss init -p ```javascript /** @type {import('tailwindcss').Config} */ -module.exports = { +export default { // ... - content: ['./index.html', './src/**/*.svelte', './node_modules/stdf/**/*.svelte'], + content: ['./src/**/*.{html,js,svelte,ts}', './node_modules/stdf/**/*.svelte'], theme: { colors: { // 主题色 - primary: '#0B24FB', - dark: '#FFC043', - blue: '#0B24FB', // primary 别名 - yellow: '#FFC043', // dark 别名 - - // 扩展色 - purple: '#7356BF', - green: '#05944F', - orange: '#FF6937', + primary: { + 50: 'rgba(var(--theme-color-primary-50), )', + 100: 'rgba(var(--theme-color-primary-100), )', + 200: 'rgba(var(--theme-color-primary-200), )', + 300: 'rgba(var(--theme-color-primary-300), )', + 400: 'rgba(var(--theme-color-primary-400), )', + 500: 'rgba(var(--theme-color-primary-500), )', + DEFAULT: 'rgba(var(--theme-color-primary), )', + 700: 'rgba(var(--theme-color-primary-700), )', + 800: 'rgba(var(--theme-color-primary-800), )', + 900: 'rgba(var(--theme-color-primary-900), )', + 950: 'rgba(var(--theme-color-primary-950), )', + }, + dark: { + 50: 'rgba(var(--theme-color-dark-50), )', + 100: 'rgba(var(--theme-color-dark-100), )', + 200: 'rgba(var(--theme-color-dark-200), )', + 300: 'rgba(var(--theme-color-dark-300), )', + 400: 'rgba(var(--theme-color-dark-400), )', + 500: 'rgba(var(--theme-color-dark-500), )', + DEFAULT: 'rgba(var(--theme-color-dark), )', + 700: 'rgba(var(--theme-color-dark-700), )', + 800: 'rgba(var(--theme-color-dark-800), )', + 900: 'rgba(var(--theme-color-dark-900), )', + 950: 'rgba(var(--theme-color-dark-950), )', + }, + primaryBlack: 'rgba(var(--theme-color-primaryBlack), )', + primaryWhite: 'rgba(var(--theme-color-primaryWhite), )', + darkBlack: 'rgba(var(--theme-color-darkBlack), )', + darkWhite: 'rgba(var(--theme-color-darkWhite), )', // 功能色 - success: '#11BB8D', - warning: '#B95000', - error: '#DA1414', - info: '#2E5AAC', + success: 'rgba(var(--theme-color-functional-success), )', + warning: 'rgba(var(--theme-color-functional-warning), )', + error: 'rgba(var(--theme-color-functional-error), )', + info: 'rgba(var(--theme-color-functional-info), )', + + // 扩展色 + extend0: 'rgba(var(--theme-color-extend0), )', + extend1: 'rgba(var(--theme-color-extend1), )', + extend2: 'rgba(var(--theme-color-extend2), )', // 中性色 black: '#000000', - white: '#fff', - gray1: '#23262B', - gray2: '#2A2B2F', - gray3: '#303239', - gray4: '#373940', - gray5: '#414249', - gray6: '#747B84', - gray7: '#DADEE3', - gray8: '#EBEEF2', - gray9: '#F4F6F9', - gray10: '#FAFAFB', + white: '#ffffff', + gray: { + 50: '#f2f2f2', + 100: '#e6e6e6', + 200: '#cccccc', + 300: '#b3b3b3', + 400: '#999999', + 500: '#808080', + 600: '#666666', + 700: '#4D4D4D', + 800: '#333333', + 900: '#1A1A1A', + 950: '#0D0D0D', + }, transparent: 'transparent', }, + // ... }, darkMode: 'class', // ... diff --git a/doc/guide/quickStart_en.md b/doc/guide/quickStart_en.md index 0173d33c..aeaff5f7 100644 --- a/doc/guide/quickStart_en.md +++ b/doc/guide/quickStart_en.md @@ -68,43 +68,73 @@ Note: The 'content' in the Tailwind configuration file represents all files that ```javascript /** @type {import('tailwindcss').Config} */ -module.exports = { +export default { // ... - content: ['./index.html', './src/**/*.svelte', './node_modules/stdf/**/*.svelte'], + content: ['./src/**/*.{html,js,svelte,ts}', './node_modules/stdf/**/*.svelte'], theme: { colors: { - // Theme Color - primary: '#0B24FB', - dark: '#FFC043', - blue: '#0B24FB', // primary alias - yellow: '#FFC043', // dark alias - - // Extended Color - purple: '#7356BF', - green: '#05944F', - orange: '#FF6937', - - // Functional Color - success: '#11BB8D', - warning: '#B95000', - error: '#DA1414', - info: '#2E5AAC', - - // Neutral Color + // Theme color + primary: { + 50: 'rgba(var(--theme-color-primary-50), )', + 100: 'rgba(var(--theme-color-primary-100), )', + 200: 'rgba(var(--theme-color-primary-200), )', + 300: 'rgba(var(--theme-color-primary-300), )', + 400: 'rgba(var(--theme-color-primary-400), )', + 500: 'rgba(var(--theme-color-primary-500), )', + DEFAULT: 'rgba(var(--theme-color-primary), )', + 700: 'rgba(var(--theme-color-primary-700), )', + 800: 'rgba(var(--theme-color-primary-800), )', + 900: 'rgba(var(--theme-color-primary-900), )', + 950: 'rgba(var(--theme-color-primary-950), )', + }, + dark: { + 50: 'rgba(var(--theme-color-dark-50), )', + 100: 'rgba(var(--theme-color-dark-100), )', + 200: 'rgba(var(--theme-color-dark-200), )', + 300: 'rgba(var(--theme-color-dark-300), )', + 400: 'rgba(var(--theme-color-dark-400), )', + 500: 'rgba(var(--theme-color-dark-500), )', + DEFAULT: 'rgba(var(--theme-color-dark), )', + 700: 'rgba(var(--theme-color-dark-700), )', + 800: 'rgba(var(--theme-color-dark-800), )', + 900: 'rgba(var(--theme-color-dark-900), )', + 950: 'rgba(var(--theme-color-dark-950), )', + }, + primaryBlack: 'rgba(var(--theme-color-primaryBlack), )', + primaryWhite: 'rgba(var(--theme-color-primaryWhite), )', + darkBlack: 'rgba(var(--theme-color-darkBlack), )', + darkWhite: 'rgba(var(--theme-color-darkWhite), )', + + // Functional color + success: 'rgba(var(--theme-color-functional-success), )', + warning: 'rgba(var(--theme-color-functional-warning), )', + error: 'rgba(var(--theme-color-functional-error), )', + info: 'rgba(var(--theme-color-functional-info), )', + + // Extended color + extend0: 'rgba(var(--theme-color-extend0), )', + extend1: 'rgba(var(--theme-color-extend1), )', + extend2: 'rgba(var(--theme-color-extend2), )', + + // Neutral color black: '#000000', - white: '#fff', - gray1: '#23262B', - gray2: '#2A2B2F', - gray3: '#303239', - gray4: '#373940', - gray5: '#414249', - gray6: '#747B84', - gray7: '#DADEE3', - gray8: '#EBEEF2', - gray9: '#F4F6F9', - gray10: '#FAFAFB', + white: '#ffffff', + gray: { + 50: '#f2f2f2', + 100: '#e6e6e6', + 200: '#cccccc', + 300: '#b3b3b3', + 400: '#999999', + 500: '#808080', + 600: '#666666', + 700: '#4D4D4D', + 800: '#333333', + 900: '#1A1A1A', + 950: '#0D0D0D', + }, transparent: 'transparent', }, + // ... }, darkMode: 'class', // ... diff --git a/doc/guide/theme.md b/doc/guide/theme.md index de069b0c..26ea0dea 100644 --- a/doc/guide/theme.md +++ b/doc/guide/theme.md @@ -1,3 +1,5 @@ +> 从 0.4.0 版本开始，STDF 支持多主题切换。 + ## 亮暗模式 ### 配置 @@ -6,42 +8,247 @@ ### 切换 -直接给 `html` 标签添加或删除 `dark` 类名即可。 +从 0.4.0 版本开始，STDF 将切换亮暗模式的方法置于 STDF 的 NPM 包中，本质上是直接给 `html` 标签添加或删除 `dark` 类名。 + +```javascript +// 引入 darkMode，传入 false 切换为亮色模式，不传参或传入 true 切换为暗色模式。 +import { darkMode } from 'stdf/theme'; -```js // 切换为亮色模式 -document.documentElement.classList.remove('dark'); +darkMode(false); // 切换为暗色模式 -document.documentElement.classList.add('dark'); +darkMode(); +``` + +## 多主题模式 + +### 介绍 + +从 0.4.0 版本开始，STDF 支持多主题切换，主题暂支持切换[颜色系统](/#/guide?nav=color)，后续考虑字体、间距、文字大小等配置也可跟随主题切换。本质原理是将一些属性设置为 CSS 变量，通过修改这些变量实现主题切换。 + +### 配置 + +请参考主题生成器生成的主题配置格式配置好主题，主题配置须包含 name 与 color 两个属性，name 为主题名称，color 为此主题搭配的颜色。默认主题配置如下： + +> 可到主题生成器快速配置颜色系统并生成配置文件。 + +```javascript +{ + name: 'STDF', + color: { + primary: { + 50: '245, 248, 255', // #F5F8FF + 100: '232, 238, 255', // #E8EEFF + 200: '187, 203, 254', // #BBCBFE + 300: '143, 165, 253', // #8FA5FD + 400: '99, 124, 253', // #637CFD + 500: '55, 81, 252', // #3751FC + default: '11, 36, 251', // #0B24FB + 700: '7, 20, 207', // #0714CF + 800: '4, 9, 164', // #0409A4 + 900: '1, 1, 120', // #010178 + 950: '3, 0, 77', // #03004D + }, + dark: { + 50: '255, 254, 245', // #FFFEF5 + 100: '255, 251, 232', // #FFFBE8 + 200: '255, 244, 199', // #FFF4C7 + 300: '255, 234, 166', // #FFEAA6 + 400: '255, 222, 133', // #FFDE85 + 500: '255, 209, 100', // #FFD164 + default: '255, 192, 67', // #FFC043 + 700: '210, 148, 41', // #D29429 + 800: '166, 108, 22', // #A66C16 + 900: '121, 72, 8', // #794808 + 950: '77, 41, 0', // #4D2900 + }, + primaryBlack: '1, 3, 25', // #010319 + primaryWhite: '242, 242, 243', // #F2F2F3 + darkBlack: '25, 17, 1', // #191101 + darkWhite: '243, 242, 242', // #F3F2F2 + functional: { + success: '17, 187, 141', // #11bb8d + warning: '185, 80, 0', // #b95000 + error: '218, 20, 20', // #da1414 + info: '46, 90, 172', // #2e5aac + }, + extend: [ + { color: '0, 172, 238', alias: "Twitter" }, // #00acee + { color: '255, 105, 55', alias: "Svelte" }, // #ff6937 + { color: '0, 112, 74', alias: "Starbucks" }, // #00704a + ], + }, +} +``` + +按照 Tailwind 的规定，使用 CSS 变量同时支持 `primary/50` 这种透明度写法，在 `tailwind.config.js` 中配置 `theme.extend.colors` 时不能使用十六进制，必须使用带有 alpha 通道写法，STDF 统一采用 rgba 写法。需要**特别注意初始 CSS 变量时只需要将 rgb 的三个值列举出来**，参考 [Using CSS variables](https://tailwindcss.com/docs/customizing-colors#using-css-variables)。 + +```css +/* ✅ ✅ 这种写法是对的 */ +:root { + --color-primary: 255 115 179; + --color-dark: 111 114 185; +} +``` + +```css +/* ❌ ❌ 这种写法是错的 */ +:root { + --color-primary: rgb(255 115 179); + --color-secondary: rgb(111 114 185); +} +``` + +按照颜色系统的配色，加上基础的黑、白、灰、透明，在 `tailwind.config.js` 中配置 `theme.extend.colors` 时至少包含以下内容： + +```javascript +/** @type {import('tailwindcss').Config} */ +// ... +module.exports = { + // ... + theme: { + colors: { + primary: { + 50: 'rgba(var(--theme-color-primary-50), )', + 100: 'rgba(var(--theme-color-primary-100), )', + 200: 'rgba(var(--theme-color-primary-200), )', + 300: 'rgba(var(--theme-color-primary-300), )', + 400: 'rgba(var(--theme-color-primary-400), )', + 500: 'rgba(var(--theme-color-primary-500), )', + DEFAULT: 'rgba(var(--theme-color-primary), )', + 700: 'rgba(var(--theme-color-primary-700), )', + 800: 'rgba(var(--theme-color-primary-800), )', + 900: 'rgba(var(--theme-color-primary-900), )', + 950: 'rgba(var(--theme-color-primary-950), )', + }, + dark: { + 50: 'rgba(var(--theme-color-dark-50), )', + 100: 'rgba(var(--theme-color-dark-100), )', + 200: 'rgba(var(--theme-color-dark-200), )', + 300: 'rgba(var(--theme-color-dark-300), )', + 400: 'rgba(var(--theme-color-dark-400), )', + 500: 'rgba(var(--theme-color-dark-500), )', + DEFAULT: 'rgba(var(--theme-color-dark), )', + 700: 'rgba(var(--theme-color-dark-700), )', + 800: 'rgba(var(--theme-color-dark-800), )', + 900: 'rgba(var(--theme-color-dark-900), )', + 950: 'rgba(var(--theme-color-dark-950), )', + }, + primaryBlack: 'rgba(var(--theme-color-primaryBlack), )', + primaryWhite: 'rgba(var(--theme-color-primaryWhite), )', + darkBlack: 'rgba(var(--theme-color-darkBlack), )', + darkWhite: 'rgba(var(--theme-color-darkWhite), )', + success: 'rgba(var(--theme-color-functional-success), )', + warning: 'rgba(var(--theme-color-functional-warning), )', + error: 'rgba(var(--theme-color-functional-error), )', + info: 'rgba(var(--theme-color-functional-info), )', + extend0: 'rgba(var(--theme-color-extend0), )', + extend1: 'rgba(var(--theme-color-extend1), )', + extend2: 'rgba(var(--theme-color-extend2), )', + black: '#000000', + white: '#ffffff', + gray: { + 50: '#f2f2f2', + 100: '#e6e6e6', + 200: '#cccccc', + 300: '#b3b3b3', + 400: '#999999', + 500: '#808080', + 600: '#666666', + 700: '#4D4D4D', + 800: '#333333', + 900: '#1A1A1A', + 950: '#0D0D0D', + }, + transparent: 'transparent', + // ... + }, + // ... + }, + darkMode: 'class', + // ... +}; ``` -## 颜色配置 - -基于 Tailwind 的配置文件 `tailwind.config.js` 配置主题颜色系统，请确保配置以下几种基本颜色。可参考 [STDF 指南 - 色彩](/#/guide?nav=color)。 - -| 颜色名称 | 说明 | 默认值 | -| ----------- | ----------------- | ----------- | -| primary | 主题色 - 亮色模式 | #0B24FB | -| dark | 主题色 - 暗色模式 | #FFC043 | -| success | 功能色 - 成功 | #11BB8D | -| warning | 功能色 - 警告 | #B95000 | -| error | 功能色 - 错误 | #DA1414 | -| info | 功能色 - 信息 | #2E5AAC | -| purple | 扩展色 - 紫色 | #7356BF | -| green | 扩展色 - 绿色 | #05944F | -| orange | 扩展色 - 橙色 | #FF6937 | -| black | 辅助色 - 黑色 | #09101D | -| gray1 | 辅助色 - 灰度 1 | #23262B | -| gray2 | 辅助色 - 灰度 2 | #2A2B2F | -| gray3 | 辅助色 - 灰度 3 | #303239 | -| gray4 | 辅助色 - 灰度 4 | #373940 | -| gray5 | 辅助色 - 灰度 5 | #414249 | -| gray6 | 辅助色 - 灰度 6 | #747B84 | -| gray7 | 辅助色 - 灰度 7 | #DADEE3 | -| gray8 | 辅助色 - 灰度 8 | #EBEEF2 | -| gray9 | 辅助色 - 灰度 9 | #F4F6F9 | -| gray10 | 辅助色 - 灰度 10 | #FAFAFB | -| transparent | 辅助色 - 透明色 | transparent | - -改变这些颜色色值将切换为不同的主题色。 +最后在全局样式增加初始主题的 CSS 变量，如在 `src/app.css` 中配置如下： + +```css +@tailwind base; +@tailwind components; +@tailwind utilities; + +@layer base { + :root { + --theme-color-primary-50: 245, 248, 255; + --theme-color-primary-100: 232, 238, 255; + --theme-color-primary-200: 187, 203, 254; + --theme-color-primary-300: 143, 165, 253; + --theme-color-primary-400: 99, 124, 253; + --theme-color-primary-500: 55, 81, 252; + --theme-color-primary: 11, 36, 251; + --theme-color-primary-700: 7, 20, 207; + --theme-color-primary-800: 4, 9, 164; + --theme-color-primary-900: 1, 1, 120; + --theme-color-primary-950: 3, 0, 77; + --theme-color-dark-50: 255, 254, 245; + --theme-color-dark-100: 255, 251, 232; + --theme-color-dark-200: 255, 244, 199; + --theme-color-dark-300: 255, 234, 166; + --theme-color-dark-400: 255, 222, 133; + --theme-color-dark-500: 255, 209, 100; + --theme-color-dark: 255, 192, 67; + --theme-color-dark-700: 210, 148, 41; + --theme-color-dark-800: 166, 108, 22; + --theme-color-dark-900: 121, 72, 8; + --theme-color-dark-950: 77, 41, 0; + --theme-color-primaryBlack: 1, 3, 25; + --theme-color-primaryWhite: 242, 242, 243; + --theme-color-darkBlack: 25, 17, 1; + --theme-color-darkWhite: 243, 242, 242; + --theme-color-functional-success: 17, 187, 141; + --theme-color-functional-warning: 185, 80, 0; + --theme-color-functional-error: 218, 20, 20; + --theme-color-functional-info: 46, 90, 172; + --theme-color-extend0: 0, 172, 238; + --theme-color-extend1: 255, 105, 55; + --theme-color-extend2: 0, 112, 74; + } +} +``` + +> 请注意，这里的 CSS 变量名必须与 `tailwind.config.js` 中的颜色系统配置一致，否则无法切换主题。extend 数量不限，但不同主题的 extend 数量必须一致。 + +### 切换 + +引入 NPM 包中的 switchTheme 方法切换主题，传入主题文件对象即可。 + +```javascript +// 引入 STDF 主题配置文件和切换主题方法（stdf 的 NPM 包中包含一个 stdf 主题配置文件） +import { stdfTheme, switchTheme } from 'stdf/theme'; +// 引入自定义主题配置文件，假定 customTheme 为自定义主题配置文件 +import customTheme from './customTheme'; + +// 切换主题为 STDF 主题 +switchTheme(stdfTheme); + +// 切换主题为自定义主题 +switchTheme(customTheme); +``` + +详细使用方式可参考 [STDF Demo](https://github.com/dufu1991/demo-stdf)。 + +## 总结 + +### 亮暗模式 + +直接使用 STDF 的 NPM 包中的 darkMode 方法即可。 + +### 多主题模式 + +1. 在入口 CSS 文件内配置主题 CSS 变量，如 `src/app.css`。 +2. 在 `tailwind.config.js` 中配置主题颜色系统。 +3. 到主题生成器中配置颜色系统并生成主题配置文件。 +4. 在需要切换主题的地方引入主题配置文件和切换主题方法，调用切换主题方法。 + +> 当然，如果你不需要切换主题，只需要配置初始 CSS 变量并在 `tailwind.config.js` 中配置颜色系统即可。 diff --git a/doc/guide/theme_en.md b/doc/guide/theme_en.md index c4677433..2a596467 100644 --- a/doc/guide/theme_en.md +++ b/doc/guide/theme_en.md @@ -1,47 +1,252 @@ -## Light/Dark Mode +## Light and dark modes ### Configuration -To use Tailwind CSS's dark mode configuration, please configure `darkMode: 'class'` in `tailwind.config.js`. Refer to [Dark Mode](https://tailwindcss.com/docs/dark-mode) for more information. +To use the dark mode configuration of Tailwind CSS, please configure `darkMode: 'class'` in `tailwind.config.js`, refer to [Dark Mode](https://tailwindcss.com/docs/dark-mode). -### Switching Modes +### Switching -Simply add or remove the `dark` class name to the `html` tag. +Starting from version 0.4.0, STDF puts the method of switching between light and dark modes in the STDF NPM package, which is essentially to add or remove the `dark` class name to the `html` tag. + +```javascript +// Import darkMode, pass false to switch to light mode, pass no parameters or pass true to switch to dark mode. +import { darkMode } from 'stdf/theme'; -```js // Switch to light mode -document.documentElement.classList.remove('dark'); +darkMode(false); // Switch to dark mode -document.documentElement.classList.add('dark'); +darkMode(); +``` + +## Multiple themes + +### Introduction + +Starting from version 0.4.0, STDF supports switching between multiple themes. The theme currently supports switching [color systems](/#/guide?nav=color), and it is considered that font, spacing, text size and other configurations can also follow the theme switching. The essential principle is to set some attributes as CSS variables, and modify these variables to achieve theme switching. + +### Configuration + +Please refer to the theme generator to generate the theme configuration format and configure the theme. The theme configuration must include the `name` and `color` attributes. The `name` is the theme name, and the `color` is the color matching of this theme. The default theme configuration is as follows: + +> You can go to the Theme Generator to quickly configure the color system and generate the configuration file. + +```javascript +{ + name: 'STDF', + color: { + primary: { + 50: '245, 248, 255', // #F5F8FF + 100: '232, 238, 255', // #E8EEFF + 200: '187, 203, 254', // #BBCBFE + 300: '143, 165, 253', // #8FA5FD + 400: '99, 124, 253', // #637CFD + 500: '55, 81, 252', // #3751FC + default: '11, 36, 251', // #0B24FB + 700: '7, 20, 207', // #0714CF + 800: '4, 9, 164', // #0409A4 + 900: '1, 1, 120', // #010178 + 950: '3, 0, 77', // #03004D + }, + dark: { + 50: '255, 254, 245', // #FFFEF5 + 100: '255, 251, 232', // #FFFBE8 + 200: '255, 244, 199', // #FFF4C7 + 300: '255, 234, 166', // #FFEAA6 + 400: '255, 222, 133', // #FFDE85 + 500: '255, 209, 100', // #FFD164 + default: '255, 192, 67', // #FFC043 + 700: '210, 148, 41', // #D29429 + 800: '166, 108, 22', // #A66C16 + 900: '121, 72, 8', // #794808 + 950: '77, 41, 0', // #4D2900 + }, + primaryBlack: '1, 3, 25', // #010319 + primaryWhite: '242, 242, 243', // #F2F2F3 + darkBlack: '25, 17, 1', // #191101 + darkWhite: '243, 242, 242', // #F3F2F2 + functional: { + success: '17, 187, 141', // #11bb8d + warning: '185, 80, 0', // #b95000 + error: '218, 20, 20', // #da1414 + info: '46, 90, 172', // #2e5aac + }, + extend: [ + { color: '0, 172, 238', alias: "Twitter" }, // #00acee + { color: '255, 105, 55', alias: "Svelte" }, // #ff6937 + { color: '0, 112, 74', alias: "Starbucks" }, // #00704a + ], + }, +} +``` + +According to the Tailwind rules, the `primary/50` this kind of transparency writing method is supported by using CSS variables at the same time. When configuring `theme.extend.colors` in `tailwind.config.js`, hexadecimal cannot be used, and the writing method with alpha channel must be used. STDF uniformly adopts the rgba writing method. You need to **pay special attention to the initial CSS variables, you only need to list the three values ​​of rgb**, refer to [Using CSS variables](https://tailwindcss.com/docs/customizing-colors#using-css-variables). + +```css +/* ✅ ✅ This writing method is correct */ +:root { + --color-primary: 255 115 179; + --color-dark: 111 114 185; +} +``` + +```css +/* ❌ ❌ This writing method is wrong */ +:root { + --color-primary: rgb(255 115 179); + --color-secondary: rgb(111 114 185); +} +``` + +According to the color system's color matching, plus the basic black, white, gray, and transparency, when configuring `theme.extend.colors` in `tailwind.config.js`, at least the following contents must be included: + +```javascript +/** @type {import('tailwindcss').Config} */ +// ... +module.exports = { + // ... + theme: { + colors: { + primary: { + 50: 'rgba(var(--theme-color-primary-50), )', + 100: 'rgba(var(--theme-color-primary-100), )', + 200: 'rgba(var(--theme-color-primary-200), )', + 300: 'rgba(var(--theme-color-primary-300), )', + 400: 'rgba(var(--theme-color-primary-400), )', + 500: 'rgba(var(--theme-color-primary-500), )', + DEFAULT: 'rgba(var(--theme-color-primary), )', + 700: 'rgba(var(--theme-color-primary-700), )', + 800: 'rgba(var(--theme-color-primary-800), )', + 900: 'rgba(var(--theme-color-primary-900), )', + 950: 'rgba(var(--theme-color-primary-950), )', + }, + dark: { + 50: 'rgba(var(--theme-color-dark-50), )', + 100: 'rgba(var(--theme-color-dark-100), )', + 200: 'rgba(var(--theme-color-dark-200), )', + 300: 'rgba(var(--theme-color-dark-300), )', + 400: 'rgba(var(--theme-color-dark-400), )', + 500: 'rgba(var(--theme-color-dark-500), )', + DEFAULT: 'rgba(var(--theme-color-dark), )', + 700: 'rgba(var(--theme-color-dark-700), )', + 800: 'rgba(var(--theme-color-dark-800), )', + 900: 'rgba(var(--theme-color-dark-900), )', + 950: 'rgba(var(--theme-color-dark-950), )', + }, + primaryBlack: 'rgba(var(--theme-color-primaryBlack), )', + primaryWhite: 'rgba(var(--theme-color-primaryWhite), )', + darkBlack: 'rgba(var(--theme-color-darkBlack), )', + darkWhite: 'rgba(var(--theme-color-darkWhite), )', + success: 'rgba(var(--theme-color-functional-success), )', + warning: 'rgba(var(--theme-color-functional-warning), )', + error: 'rgba(var(--theme-color-functional-error), )', + info: 'rgba(var(--theme-color-functional-info), )', + extend0: 'rgba(var(--theme-color-extend0), )', + extend1: 'rgba(var(--theme-color-extend1), )', + extend2: 'rgba(var(--theme-color-extend2), )', + black: '#000000', + white: '#ffffff', + gray: { + 50: '#f2f2f2', + 100: '#e6e6e6', + 200: '#cccccc', + 300: '#b3b3b3', + 400: '#999999', + 500: '#808080', + 600: '#666666', + 700: '#4D4D4D', + 800: '#333333', + 900: '#1A1A1A', + 950: '#0D0D0D', + }, + transparent: 'transparent', + // ... + }, + // ... + }, + darkMode: 'class', + // ... +}; ``` -## Color Configuration - -Based on the Tailwind configuration file `tailwind.config.js`, configure the theme color system. Please ensure that the following basic colors are configured. Reference [STDF Guide - Color](/#/Guide?nav=color). - -| Color Name | Description | Default Value | -| ----------- | ------------------------------ | ------------- | -| primary | Theme color - light mode | #0B24FB | -| dark | Theme color - dark mode | #FFC043 | -| success | Functional color - success | #11BB8D | -| warning | Functional color - warning | #B95000 | -| error | Functional color - error | #DA1414 | -| info | Functional color - information | #2E5AAC | -| purple | Extended color - purple | #7356BF | -| green | Extended color - green | #05944F | -| orange | Extended color - orange | #FF6937 | -| black | Auxiliary color - black | #09101D | -| gray1 | Auxiliary color - gray 1 | #23262B | -| gray2 | Auxiliary color - gray 2 | #2A2B2F | -| gray3 | Auxiliary color - gray 3 | #303239 | -| gray4 | Auxiliary color - gray 4 | #373940 | -| gray5 | Auxiliary color - gray 5 | #414249 | -| gray6 | Auxiliary color - gray 6 | #747B84 | -| gray7 | Auxiliary color - gray 7 | #DADEE3 | -| gray8 | Auxiliary color - gray 8 | #EBEEF2 | -| gray9 | Auxiliary color - gray 9 | #F4F6F9 | -| gray10 | Auxiliary color - gray 10 | #FAFAFB | -| transparent | Auxiliary color - transparent | transparent | - -Changing these color values will switch to different theme colors. +Finally, add the initial theme CSS variables in the global style, such as `src/app.css`: + +```css +@tailwind base; +@tailwind components; +@tailwind utilities; + +@layer base { + :root { + --theme-color-primary-50: 245, 248, 255; + --theme-color-primary-100: 232, 238, 255; + --theme-color-primary-200: 187, 203, 254; + --theme-color-primary-300: 143, 165, 253; + --theme-color-primary-400: 99, 124, 253; + --theme-color-primary-500: 55, 81, 252; + --theme-color-primary: 11, 36, 251; + --theme-color-primary-700: 7, 20, 207; + --theme-color-primary-800: 4, 9, 164; + --theme-color-primary-900: 1, 1, 120; + --theme-color-primary-950: 3, 0, 77; + --theme-color-dark-50: 255, 254, 245; + --theme-color-dark-100: 255, 251, 232; + --theme-color-dark-200: 255, 244, 199; + --theme-color-dark-300: 255, 234, 166; + --theme-color-dark-400: 255, 222, 133; + --theme-color-dark-500: 255, 209, 100; + --theme-color-dark: 255, 192, 67; + --theme-color-dark-700: 210, 148, 41; + --theme-color-dark-800: 166, 108, 22; + --theme-color-dark-900: 121, 72, 8; + --theme-color-dark-950: 77, 41, 0; + --theme-color-primaryBlack: 1, 3, 25; + --theme-color-primaryWhite: 242, 242, 243; + --theme-color-darkBlack: 25, 17, 1; + --theme-color-darkWhite: 243, 242, 242; + --theme-color-functional-success: 17, 187, 141; + --theme-color-functional-warning: 185, 80, 0; + --theme-color-functional-error: 218, 20, 20; + --theme-color-functional-info: 46, 90, 172; + --theme-color-extend0: 0, 172, 238; + --theme-color-extend1: 255, 105, 55; + --theme-color-extend2: 0, 112, 74; + } +} +``` + +> Please note that the CSS variable names here must be consistent with the color system configuration in `tailwind.config.js`, otherwise the theme cannot be switched. + +### Switching + +Import the theme configuration file and the switchTheme method in the NPM package of STDF to switch the theme, and pass in the theme file object. + +```javascript +// Import STDF theme configuration file and switch theme method (stdf NPM package contains a stdf theme configuration file) +import { stdfTheme, switchTheme } from 'stdf/theme'; +// Import custom theme configuration file, assuming customTheme is a custom theme configuration file +import customTheme from './customTheme'; + +// Switch theme to STDF theme +switchTheme(stdfTheme); + +// Switch theme to custom theme +switchTheme(customTheme); +``` + +For detailed usage, please refer to [STDF Demo](https://github.com/dufu1991/demo-stdf). + +## Summary + +### Light and dark modes + +Use the darkMode method in the STDF NPM package directly. + +### Multiple themes + +1. Configure the theme CSS variables in the entry CSS file, such as `src/app.css`. +2. Configure the theme color system in `tailwind.config.js`. +3. Go to the theme generator to configure the color system and generate the theme configuration file. +4. Import the theme configuration file and the switch theme method where you need to switch the theme, and call the switch theme method. + +> Of course, if you don’t need to switch themes, you only need to configure the initial CSS variables and configure the color system in `tailwind.config.js`.