docs: add customize.md and publish all design resources (#29)

- add customize.md - publish all design resources - fix #19 - update usage.md and install.md for v1.3.0
qwd · Jan 18, 2023 · 81ac6a7 · 81ac6a7
1 parent 3349b67
commit 81ac6a7
Show file tree

Hide file tree

Showing 7 changed files with 181 additions and 41 deletions.
diff --git a/config.yml b/config.yml
@@ -68,9 +68,12 @@ languages:
       - name: 使用
         url: /usage/
         weight: 3
+      - name: 自定义
+        url: /customize/
+        weight: 4
       - name: 图标预览
         url: /icons/
-        weight: 4
+        weight: 5
       footer:
       - name: dev
         weight: 1
@@ -136,9 +139,12 @@ languages:
       - name: Usage
         url: /usage/
         weight: 3
+      - name: Customize
+        url: /customize/
+        weight: 4
       - name: Icons
         url: /icons/
-        weight: 4
+        weight: 5
       footer:
       - name: dev
         weight: 1

diff --git a/docs/content/customize.en.md b/docs/content/customize.en.md
@@ -0,0 +1,58 @@
+---
+title: Customize
+description: QWeather Icons project helps you create customized icons and icon fonts.
+---
+
+You may want to change the icons color or redesign the icons to better fit your project style. Here's how to create your customized icons and fonts using the QWeather Icons project.
+
+## Edit Icons and Fonts
+
+👉 [Get all design resources in Figma](https://www.figma.com/community/file/1196353857920331062)
+
+You can change the color or redesign these icons, and then export new images in SVG or other formats.
+
+If you need to create new fonts, you must:
+
+- Export the icons in SVG format.
+- SVGs must be **Flatten** and **Outline stroke**
+- Make sure the value of `fill-rule` for SVGs **IS NOT** `evenodd`. If you are editing in Figma, it is recommended to use [Fill Rule Editor](https://www.figma.com/community/plugin/771155994770327940) to fix it.
+
+Once your icons and fonts are redesigned, go to [Run QWeather Icons](#run-qweather-icons) below to optimize the SVGs (we use [SVGO](https://github.com/svg/svgo)) and create the icon fonts.
+
+## Run QWeather Icons
+
+The QWeather Icons project will help you optimize SVGs and create new icon fonts.
+
+#### 1. Install Node.js
+
+[Download and install Node.js](https://nodejs.org), we tested in v14 and v18. Typically, other versions are supported as well.
+
+#### 2. Download source code for QWeather Icons 
+
+```sh
+git clone https://github.com/qwd/Icons.git
+```
+
+#### 3. Import customized SVGs
+
+Paste all your customized SVGs into the `/icons` and replace the original SVGs.
+
+If there are new/deleted/renamed SVGs, you need to edit the `icons-list.json` file.
+
+#### 4. Install Dependencies
+
+Go into the project directory and install the dependencies (this may take some time depending on your network environment):
+
+```
+npm install
+```
+
+#### 5. Run
+
+```
+npm run icons
+```
+
+Wait a moment, all SVGs are generated in `/icons`, and fonts are generated in `/font`, you can also open `/font/demo.html` to see the demo.
+
+Done 🎉
diff --git a/docs/content/customize.md b/docs/content/customize.md
@@ -0,0 +1,58 @@
+---
+title: 自定义
+description: QWeather Icons 项目可以帮助你创建自定义图标和图标字体。
+---
+
+各花入各眼，你可能希望修改图标的颜色，或者修改一些图标样式以更加适配你的设计风格，这里将介绍如何使用和风天气项目创建你的自定义图标和字体。
+
+## 编辑图标和字体 {#edit-icons-and-fonts}
+
+👉 [在Figma中获取所有设计文件](https://www.figma.com/community/file/1196353857920331062)
+
+你可以对这些图标修改颜色或调整样式，然后导出新的SVG或其他格式的图片。
+
+如果需要创建新的字体，你必须：
+
+- 导出SVG格式的图标
+- SVG图片必须进行**Flatten**和**Outline stroke**操作
+- 确保SVG图片的`fill-rule`的值**不是**`evenodd`。如果你是在Figma中进行的编辑，推荐使用[Fill Rule Editor](https://www.figma.com/community/plugin/771155994770327940)这个插件来修正。
+
+当完成上述图标和字体的重新设计后，参考下方[运行QWeather Icons](#run-qweather-icons)，可以对SVG图标进行压缩和优化（我们使用[SVGO](https://github.com/svg/svgo)）并创建字体。
+
+## 运行 QWeather Icons {#run-qweather-icons}
+
+QWeather Icons项目将帮助你优化SVG图标和创建新的字体。
+
+#### 1. 安装Node.js
+
+请访问 <https://nodejs.org> 下载并安装Node.js，我们在v14和v18版本测试通过。
+
+#### 2. 下载项目
+
+```sh
+git clone https://github.com/qwd/Icons.git
+```
+
+#### 3. 导入自定义SVG
+
+将你修改后的所有SVG粘贴到`/icons`目录下并替换原文件。
+
+如果有新增/删除/重命名的图标，你需要编辑`icons-list.json`文件。
+
+#### 4. 安装依赖
+
+进入项目目录，安装依赖库（这可能会需要一些时间，取决于你的网络环境，或者尝试更改npm源）：
+
+```
+npm install
+```
+
+#### 5. 运行
+
+```
+npm run icons
+```
+
+稍等片刻，所有SVG图标在`/icons`目录生成，字体文件在`/font`目录下生成，你也可以打开`/font/demo.html`查看效果。
+
+搞定 🎉
diff --git a/docs/content/install.en.md b/docs/content/install.en.md
@@ -20,15 +20,12 @@ No need to install and download, import the QWeather Icons stylesheet via CDN @j
 
 ## Download
 
-Download our SVG icons, icon fonts and stylesheets that you can modify or use locally.
+[Download SVG icons and fonts](https://github.com/qwd/Icons/releases/latest/) 
 
+## Design Resources
 
-[Download QWeather Icons](https://github.com/qwd/Icons/releases/latest/)
+All design files for QWeather Icons have been published in [Figma](https://www.figma.com/community/file/1196353857920331062) and you can copy or edit these icons. Design files are licensed under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0).
 
 ## Source Code
 
-QWeather Icons is licensed under MIT and hosted on Github, you can easily access the source code.
-
-```git
-git clone https://github.com/qwd/Icons.git
-```
+See our [Github repo](https://github.com/qwd/Icons). QWeather Icons is licensed under MIT.
diff --git a/docs/content/install.md b/docs/content/install.md
@@ -1,6 +1,6 @@
 ---
 title: 下载和安装
-description: 你可以使用多种方式下载和安装和风天气图标（QWeather Icons），包括npm、CDN、打包下载甚至下载源代码。
+description: 你可以使用多种方式下载和安装和风天气图标（QWeather Icons），包括npm、CDN、下载源代码或复制设计原稿。
 ---
 
 ## npm
@@ -21,14 +21,12 @@ npm i qweather-icons
 
 ## 下载 {#download}
 
-打包下载我们的SVG图标、图标字体和样式表，你可以在本地修改或使用。
+[下载图标和字体](https://github.com/qwd/Icons/releases/latest/)
 
-[下载和风天气图标](https://github.com/qwd/Icons/releases/latest/)
+## 设计稿 {#design-resources}
 
-## 源代码 {#source-code}
+和风天气图标的所有设计文件已经发布在[Figma](https://www.figma.com/community/file/1196353857920331062)，你可以复制或编辑这些图标。图标采用[知识共享署名4.0许可](https://creativecommons.org/licenses/by/4.0/deed.zh)。
 
-和风天气图标托管在[Github](https://github.com/qwd/Icons)，你可以方便的获取源代码。
+## 源代码 {#source-code}
 
-```git
-git clone https://github.com/qwd/Icons.git
-```
+访问[Github 仓库](https://github.com/qwd/Icons)，和风天气图标项目的源代码采用[MIT许可](https://github.com/qwd/Icons/blob/main/LICENSE)。
diff --git a/docs/content/usage.en.md b/docs/content/usage.en.md
@@ -3,32 +3,44 @@ title: Usage
 description: QWeather Icons use SVG format, so it is very easy to use and modification.
 ---
 
-> For [QWeather developers](https://dev.qweather.com/docs/), the icon name or style name is the same as the `icon` field in the Weather API/SDK, so you just need to match the icon with the same name.
+> For [QWeather developers](https://dev.qweather.com/en/), the icon name or style name is the same as the `icon` in weather data or `warning.type` in warning data, so you can simply map the icons to the weather conditions.
 > 
-> **Example:** the API returns `"icon": "301"`, then you just need to use the image `301.svg` or the icon font `<i class="qi-301"></i>`.
+> **Example:** `now.icon = 301` corresponds **301.svg** or `<i class="qi-301"></i>`, `warning.type = 1010` corresponds **1010.svg** or `<i class="qi-1010"></i>`. For the icons code and name used in QWeather Develop Service, please refer to [Icon info](https://dev.qweather.com/docs/resource/icons/).
 
 ## Embedded {#embedded}
 
-Use the `svg` element to embed the icon into your HTML.
+Use the `<svg>` element to embed the icon into your HTML.
 
 ```html
-<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="qi-301" viewBox="0 0 16 16"><path d="M7.012 14.985a1 1 0 0 0 2 0 6.605 6.605 0 0 0-1-2 6.605 6.605 0 0 0-1 2zM3.959 14a1 1 0 0 0 2 0 6.605 6.605 0 0 0-1-2 6.605 6.605 0 0 0-1 2zm6.028 0a1 1 0 0 0 2 0 6.605 6.605 0 0 0-1-2 6.605 6.605 0 0 0-1 2zM5.207 1.904h.007a.5.5 0 0 0 .493-.506L5.695.494a.5.5 0 0 0-.5-.494h-.007a.5.5 0 0 0-.493.506l.012.905a.5.5 0 0 0 .5.493zm-2.892.946a.5.5 0 1 0 .698-.716l-.648-.63a.5.5 0 1 0-.697.715zm-.179 2.203a.5.5 0 0 0-.5-.493h-.007l-.905.011a.5.5 0 0 0 .007 1h.007l.904-.011a.5.5 0 0 0 .494-.507zm5.638-2.12a.5.5 0 0 0 .359-.151l.63-.648a.5.5 0 0 0-.716-.698l-.631.648a.5.5 0 0 0 .358.849z"/><path d="M12.028 5.579a2.927 2.927 0 0 0-.37.037 4.364 4.364 0 0 0-7.316 0 2.926 2.926 0 0 0-.37-.037 2.972 2.972 0 1 0 1.16 5.709 4.302 4.302 0 0 0 5.735 0 2.972 2.972 0 1 0 1.16-5.71zm0 4.944a1.959 1.959 0 0 1-.77-.156 1 1 0 0 0-1.05.168 3.303 3.303 0 0 1-4.417 0 1 1 0 0 0-1.05-.168 1.972 1.972 0 1 1-.769-3.788 1.077 1.077 0 0 1 .15.017l.095.012a1 1 0 0 0 .962-.444 3.364 3.364 0 0 1 5.642 0 1 1 0 0 0 .962.444l.095-.012a1.08 1.08 0 0 1 .15-.017 1.972 1.972 0 1 1 0 3.944zM2.482 5.315A3.53 3.53 0 0 1 3.5 5.027a1.831 1.831 0 0 1 1.81-1.603 1.81 1.81 0 0 1 .553.095 4.933 4.933 0 0 1 1.281-.405A2.82 2.82 0 0 0 2.476 5.26c0 .02.006.037.006.056z"/></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="qi-307-fill" viewBox="0 0 16 16"><path d="M1 12.5a1 1 0 1 0 2 0c0-.5-.555-1.395-1-2-.445.605-1 1.5-1 2ZM5 15a1 1 0 1 0 2 0c0-.5-.555-1.395-1-2-.445.605-1 1.5-1 2Zm4.293.707A1 1 0 0 1 9 15c0-.5.555-1.395 1-2 .445.605 1 1.5 1 2a1 1 0 0 1-1.707.707ZM13 12.5a1 1 0 0 0 2 0c0-.5-.555-1.395-1-2-.445.605-1 1.5-1 2Zm-1.273-4.283A4.99 4.99 0 0 1 7.9 10a4.988 4.988 0 0 1-3.773-1.719 3 3 0 1 1-.586-5.732A4.998 4.998 0 0 1 7.9 0a4.999 4.999 0 0 1 4.38 2.587 3 3 0 1 1-.553 5.63Z"/></svg>
 ```
 
-## img element {#img-element}
+## \<img> element {#img-element}
 
-SVG can also be treated as a normal image, just insert the image in the HTML using the `img` element as usual.
+SVG can also be treated as a normal image, just insert the image in the HTML using the `<img>` element as usual.
 
 ```html
 <img src="/some/path/301.svg" alt="QWeather" width="32" height="32">
 ```
 
 ## Icon font {#icon-font}
 
-QWeather Icons provides icon fonts that you can use like any other icon font when you introduce the stylesheet [using CDN](/install/#cdn) or import it in your local project.
+QWeather Icons provides icon fonts, and just like using other icon fonts, you can import font styles using [CDN](/install/#cdn) or [locally](https://github.com/qwd/Icons/releases/latest/).
+
 
 ```html
-<i class="qi-301"></i>
+<html>
+<head>
+    <!-- import font style -->
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/qweather-icons@1.3.0/font/qweather-icons.css">
+</head>
+<body>
+    <div>
+        <!-- try "heavy rain" and "cold" icons -->
+        It's raining <i class="qi-307"></i> and cold <i class="qi-cold"></i>
+    </div>
+</body>
+</html>
 ```
 
 ## CSS
@@ -38,7 +50,7 @@ You can add SVG to your CSS, please note that the svg color needs to be `%23` in
 ```css
 .someClass::after {
   content: "";
-  background-image: url("data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill='%23066ff5' class="qi-102-fill" viewBox="0 0 16 16"><path d="M8 3a4.99 4.99 0 0 0-4.18 2.267 3.345 3.345 0 0 0-.423-.042 3.397 3.397 0 1 0 1.326 6.524 4.917 4.917 0 0 0 6.554 0 3.397 3.397 0 1 0 1.326-6.524 3.345 3.345 0 0 0-.423.042A4.99 4.99 0 0 0 8 3z"/></svg>");
+  background-image: url("data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill='%23FF843F' class="qi-100-fill" viewBox="0 0 16 16"><path d="M8.005 3.5a4.5 4.5 0 1 0 0 9 4.5 4.5 0 0 0 0-9Zm.004-.997a.5.5 0 0 1-.5-.5v-1.5a.5.5 0 0 1 1 0v1.5a.5.5 0 0 1-.5.5ZM3.766 4.255a.498.498 0 0 1-.353-.147l-1.062-1.06a.5.5 0 0 1 .707-.707L4.122 3.4a.5.5 0 0 1-.355.854v.001ZM2.004 8.493h-1.5a.5.5 0 1 1 0-1h1.5a.5.5 0 1 1 0 1Zm.691 5.303a.5.5 0 0 1-.354-.854l1.062-1.06a.5.5 0 0 1 .708.707l-1.063 1.06a.497.497 0 0 1-.353.147Zm5.301 2.201a.5.5 0 0 1-.5-.5v-1.5a.5.5 0 0 1 1 0v1.5a.5.5 0 0 1-.5.5Zm5.304-2.191a.496.496 0 0 1-.353-.147l-1.06-1.06a.5.5 0 1 1 .706-.707l1.06 1.06a.5.5 0 0 1-.353.854Zm2.203-5.299h-1.5a.5.5 0 0 1 0-1h1.5a.5.5 0 1 1 0 1ZM12.25 4.265a.5.5 0 0 1-.354-.854l1.06-1.06a.5.5 0 1 1 .708.707l-1.06 1.06a.498.498 0 0 1-.354.147Z"/></svg>");
   background-repeat: no-repeat;
 }
 ```
@@ -52,9 +64,9 @@ If you have referenced the QWeather Icons font, you can also use it like this:
   }
 ```
 
-## Download
+## Customize
 
-If you need to modify QWeather Icons, or want to use these icons elsewhere, just [download all the icons](https://github.com/qwd/Icons/releases/latest) locally to create more personalized icons and export them to various formats you like, such as .png/.jpg and etc.
+SVG is a vector graphic, so you can freely edit its style, or when you have created new designs, you can compress these icons and create icon font with QWeather Icons project. See [Customize](/en/customize/) to learn more.