feat: improve category hierarchy display

- Render complete category paths in post and home metadata
- Apply home category limits per path and support zero for all paths
- Expand mode-aware gray scales for borders and high-contrast surfaces

Author: evannotfound

docs/content/docs/en/developer/index.mdx

@@ -153,17 +153,21 @@ appropriate entry.
   page backgrounds.
 - `--rd-gray-100`, `--rd-gray-200`, and `--rd-gray-300` are for default, hover,
   and active component backgrounds, respectively.
-- `--rd-gray-alpha-400` is for structural borders and dividers.
+- `--rd-gray-400`, `--rd-gray-500`, and `--rd-gray-600` are for default, hover,
+  and active component borders, respectively.
+- `--rd-gray-700` and `--rd-gray-800` are for default and hover high-contrast
+  component backgrounds.
 - `--rd-gray-900` is for secondary text and icons; `--rd-gray-1000` is for
   primary text and icons.
+- `--rd-gray-alpha-100` through `--rd-gray-alpha-1000` mirror the solid gray
+  roles when transparency is required; `--rd-gray-alpha-400` remains the
+  standard structural border and divider.
 - `--rd-primary-text` is for text and icons on primary-colored fills.
 - `--rd-shadow` remains the complete mode-aware shadow treatment.
 
-`--rd-gray-500` through `--rd-gray-800` are intentionally undefined and must
-not be invented without a demonstrated component role. Do not add component
-aliases such as `card` or `foreground`; components should select the numbered
-variable that matches their role directly. Tailwind mappings backed by
-color-mode or configuration-generated runtime variables belong in
-`@theme inline`.
+Do not add component aliases such as `card` or `foreground`; components should
+select the numbered variable that matches their role directly. Tailwind
+mappings backed by color-mode or configuration-generated runtime variables
+belong in `@theme inline`.
 
 For more information, see the [official Tailwind CSS documentation](https://tailwindcss.com/docs).

docs/content/docs/en/home/home.mdx

@@ -165,7 +165,11 @@ home:
 
 |  Type  | Optional values | Default value |
 | :----: | :-------------: | :-----------: |
-| Number |  1, 2, 3, ...   |       3       |
+| Number |  0, 1, 2, ...   |       3       |
+
+Categories are displayed as complete hierarchy paths, such as
+`Parent › Child`. The limit counts paths rather than individual hierarchy
+segments; use `0` to display every path.
 
 ## Tags
 

docs/content/docs/zh/developer/index.mdx

@@ -104,11 +104,13 @@ pnpm release:notes:check
 
 - `--rd-background-100` 和 `--rd-background-200` 分别用于主要和交替页面背景。
 - `--rd-gray-100`、`--rd-gray-200`、`--rd-gray-300` 分别用于组件的默认、悬停和激活背景。
-- `--rd-gray-alpha-400` 用于结构边框和分隔线。
+- `--rd-gray-400`、`--rd-gray-500`、`--rd-gray-600` 分别用于组件的默认、悬停和激活边框。
+- `--rd-gray-700`、`--rd-gray-800` 分别用于高对比度组件的默认和悬停背景。
 - `--rd-gray-900` 用于次要文字和图标，`--rd-gray-1000` 用于主要文字和图标。
+- `--rd-gray-alpha-100` 至 `--rd-gray-alpha-1000` 在需要透明度时与同编号的纯色灰阶用途一致；`--rd-gray-alpha-400` 仍用于标准结构边框和分隔线。
 - `--rd-primary-text` 用于主题色填充上的文字和图标。
 - `--rd-shadow` 继续表示完整的明暗模式阴影效果。
 
-`--rd-gray-500` 至 `--rd-gray-800` 有意保持未定义；没有经过实际组件证明的职责时，不得自行补充。不要新增 `card`、`foreground` 等组件别名，组件应直接选择与职责匹配的编号变量。引用明暗模式变量或配置生成变量的 Tailwind 运行时映射必须放在 `@theme inline` 中。
+不要新增 `card`、`foreground` 等组件别名，组件应直接选择与职责匹配的编号变量。引用明暗模式变量或配置生成变量的 Tailwind 运行时映射必须放在 `@theme inline` 中。
 
 详细的 Tailwind CSS 文档请参考 [Tailwind CSS 官方文档](https://tailwindcss.com/docs)。

docs/content/docs/zh/home/home.mdx

@@ -164,7 +164,9 @@ home:
 
 | 类型 |    可选值    | 默认值 |
 | :--: | :----------: | :----: |
-| 数字 | 1, 2, 3, ... |   3    |
+| 数字 | 0, 1, 2, ... |   3    |
+
+分类会按 `父分类 › 子分类` 这样的完整层级路径显示。此限制计算的是路径数量，而不是路径中的单个分类层级；设置为 `0` 时显示全部路径。
 
 ## 标签
 

layout/pages/categories.ejs

@@ -13,7 +13,7 @@
                 <% if (category.children.length) { %>
                     <div class="flex flex-col mx-6 border border-t-0 border-rd-gray-alpha-400 bg-rd-background-200 rounded-b-xl">
                         <div class="flex items-center gap-1 text-sm text-rd-gray-800 border-b border-dotted border-rd-gray-alpha-400 px-4 py-1">
-                            <i class="fa-regular fa-diagram-subtask text-xs"></i>
+                            <i class="fa-regular fa-diagram-subtask text-xs text-rd-gray-700"></i>
                             <span><%- __('subcategories') %></span>
                         </div>
                         <ul class="relative flex flex-col py-2 px-4 pt-1">

layout/pages/home/post-card.ejs

@@ -1,5 +1,5 @@
 <!-- using ring to avoid border wrapping around post thumbnail -->
-<li data-home-card class="relative flex box-border flex-col mb-6 overflow-hidden rounded-2xl ring-inset ring ring-rd-gray-alpha-400 bg-rd-background-100 sm:mb-8 md:mb-10 group">
+<li data-home-card class="relative flex box-border flex-col mb-6 overflow-hidden rounded-2xl ring-inset ring ring-rd-gray-alpha-400 sm:mb-8 md:mb-10 group">
     <% if (post.sticky) { %>
         <div data-sticky-label class="absolute top-3 right-3 z-10 cursor-default rounded-full border border-rd-gray-alpha-400 bg-rd-background-100/15 px-2.5 py-0.5 text-xs text-rd-gray-900 hover:text-rd-gray-1000">
             <i class="fa-regular fa-thumbtack mr-1 text-xs" aria-hidden="true"></i><%- __('sticky') %>
@@ -44,9 +44,9 @@
             <% } %>
         </div>
 
-        <div class="flex items-center justify-between text-sm text-rd-gray-900">
-            <div class="tracking-normal [&_a]:text-rd-gray-900 [&_a:hover]:text-primary">
-                <span class="mr-2.5"><i class="fa-solid fa-calendars" aria-hidden="true"></i>&nbsp;
+        <div class="flex items-center justify-between gap-4 text-sm text-rd-gray-900">
+            <div class="flex min-w-0 flex-wrap items-center gap-x-2.5 gap-y-1 tracking-normal [&_a]:text-rd-gray-900 [&_a:hover]:text-primary">
+                <span class="flex items-center"><i class="fa-solid fa-calendars" aria-hidden="true"></i>&nbsp;
                     <time data-home-article-date data-date="<%= post.date %>" datetime="<%= date_xml(post.date) %>">
                         <% if (theme.home.article_date_format == 'auto' || theme.home.article_date_format == 'relative') { %>
                             <%= date(post.date, config.date_format) %>
@@ -56,29 +56,32 @@
                     </time>
                 </span>
                 <% if (post.categories.length && theme.home.categories.enable === true) { %>
-                    <span class="mr-2.5 hidden sm:inline">
-                        <i class="fa-solid fa-folders" aria-hidden="true"></i>&nbsp;
-                        <ul class="inline">
-                            <% let previousParentId = null; %>
-                            <% post.categories.forEach((category) => { %>
-                                <% if (previousParentId !== category.parent) { %>
-                                    <% if (previousParentId !== null) { %><li class="inline">></li><% } %>
-                                    <li class="inline"><a href="<%- url_for(category.path) %>"><%= category.name %></a>&nbsp;</li>
-                                <% } else { %>
-                                    <li class="inline">| <a href="<%- url_for(category.path) %>"><%= category.name %></a>&nbsp;</li>
-                                <% } %>
-                                <% previousParentId = category.parent; %>
+                    <%
+                        const categoryPaths = getCategoryPaths(post.categories);
+                        const categoryLimit = Number(theme.home.categories.limit);
+                        const visibleCategoryPaths = categoryLimit > 0 ? categoryPaths.slice(0, categoryLimit) : categoryPaths;
+                    %>
+                    <div class="hidden min-w-0 items-center gap-1.5 sm:flex">
+                        <i class="fa-regular fa-folders shrink-0" aria-hidden="true"></i>
+                        <ul class="flex min-w-0 flex-wrap gap-1.5" aria-label="<%= __('categories') %>">
+                            <% visibleCategoryPaths.forEach((categoryPath) => { %>
+                                <li data-home-category-path class="flex max-w-full items-center rounded-md border border-rd-gray-alpha-300 bg-rd-gray-100/30 px-2 py-0.5 text-xs">
+                                    <% categoryPath.forEach((category, index) => { %>
+                                        <% if (index > 0) { %><i class="fa-regular fa-angle-right mx-1 shrink-0 text-xs text-rd-gray-800" aria-hidden="true"></i><% } %>
+                                        <a class="min-w-0 truncate" href="<%- url_for(category.path) %>"><%= category.name %></a>
+                                    <% }); %>
+                                </li>
                             <% }); %>
                         </ul>
-                    </span>
+                    </div>
                 <% } %>
                 <% if (post.tags.length && theme.home.tags.enable === true) { %>
-                    <span class="mr-2.5 hidden last:mr-0 md:inline">
-                        <i class="fa-solid fa-tags" aria-hidden="true"></i>&nbsp;
-                        <ul class="inline">
+                    <span class="hidden items-center gap-1.5 md:flex">
+                        <i class="fa-solid fa-tags" aria-hidden="true"></i>
+                        <ul class="flex flex-wrap gap-1.5">
                             <% post.tags.forEach((tag, i) => { %>
                                 <% if (theme.home.tags.limit === 0 || i + 1 <= theme.home.tags.limit) { %>
-                                    <li class="inline"><%= i === 0 ? '' : '| ' %><a href="<%- url_for(tag.path) %>"><%= tag.name %></a>&nbsp;</li>
+                                    <li class="flex"><a class="rounded-full border border-rd-gray-alpha-300 bg-rd-gray-100/30 px-2 py-0.5 text-xs text-rd-gray-900 hover:bg-rd-gray-alpha-300 hover:text-primary" href="<%- url_for(tag.path) %>"><%= tag.name %></a></li>
                                 <% } %>
                             <% }); %>
                         </ul>
@@ -87,7 +90,7 @@
             </div>
 
             <a
-                class="group/read-more flex items-center gap-2"
+                class="group/read-more flex shrink-0 items-center gap-2 whitespace-nowrap"
                 href="<%- url_for(post.path) %>"
             >
                 <%- __('read_more') %>

layout/pages/post/meta.ejs

@@ -18,21 +18,20 @@
     <% } %>
 
     <% if (articleObject?.categories?.length) { %>
-        <span class="inline <%= metaItemClass %>">
-            <i class="fa-regular fa-folders" aria-hidden="true"></i>&nbsp;
-            <ul class="inline">
-                <% let previousParentId = null; %>
-                <% articleObject.categories.forEach((category) => { %>
-                    <% if (previousParentId !== category.parent) { %>
-                        <% if (previousParentId !== null) { %><li class="inline">></li><% } %>
-                        <li class="inline"><a href="<%- url_for(category.path) %>"><%= category.name %></a>&nbsp;</li>
-                    <% } else { %>
-                        <li class="inline">| <a href="<%- url_for(category.path) %>"><%= category.name %></a>&nbsp;</li>
-                    <% } %>
-                    <% previousParentId = category.parent; %>
+        <div class="inline-flex flex-wrap items-center gap-1 <%= metaItemClass %>">
+            <i class="fa-regular fa-folders shrink-0" aria-hidden="true"></i>
+            <ul class="inline-flex flex-wrap items-center gap-x-1.5 gap-y-1" aria-label="<%= __('categories') %>">
+                <% getCategoryPaths(articleObject.categories).forEach((categoryPath, pathIndex) => { %>
+                    <li data-post-category-path class="inline-flex items-center">
+                        <% if (pathIndex > 0) { %><span class="mr-1.5 text-rd-gray-800" aria-hidden="true">·</span><% } %>
+                        <% categoryPath.forEach((category, index) => { %>
+                            <% if (index > 0) { %><i class="fa-regular fa-angle-right mx-1 text-xs text-rd-gray-800" aria-hidden="true"></i><% } %>
+                            <a href="<%- url_for(category.path) %>"><%= category.name %></a>
+                        <% }); %>
+                    </li>
                 <% }); %>
             </ul>
-        </span>
+        </div>
     <% } %>
     <% if (articleObject?.tags?.length) { %>
         <span class="hidden md:inline <%= metaItemClass %>">

openspec/specs/theme-visual-system/spec.md

@@ -8,7 +8,7 @@ Define the theme's structural borders, static depth, and interaction-effect cont
 
 ### Requirement: Numbered RD colors have fixed roles
 
-Redefine SHALL provide a compact mode-aware numbered color foundation consisting of `--rd-background-100`, `--rd-background-200`, `--rd-gray-100`, `--rd-gray-200`, `--rd-gray-300`, `--rd-gray-alpha-400`, `--rd-gray-900`, and `--rd-gray-1000`. The background levels SHALL represent primary and alternate page backgrounds, gray levels 100 through 300 SHALL represent increasingly visible neutral component backgrounds, gray-alpha 400 SHALL represent the standard structural border, and gray levels 900 and 1000 SHALL represent secondary and primary text and icons.
+Redefine SHALL provide a mode-aware numbered color foundation consisting of `--rd-background-100`, `--rd-background-200`, solid `--rd-gray-100` through `--rd-gray-1000`, and translucent `--rd-gray-alpha-100` through `--rd-gray-alpha-1000`. The background levels SHALL represent primary and alternate page backgrounds; gray levels 100 through 300 SHALL represent increasingly visible neutral component backgrounds; gray levels 400 through 600 SHALL represent increasingly visible component borders; gray levels 700 and 800 SHALL represent default and hover high-contrast component backgrounds; and gray levels 900 and 1000 SHALL represent secondary and primary text and icons. Each gray-alpha level SHALL mirror the corresponding solid gray role when transparency is required, with gray-alpha 400 representing the standard structural border.
 
 #### Scenario: Contributor chooses a page background
 
@@ -21,6 +21,21 @@ Redefine SHALL provide a compact mode-aware numbered color foundation consisting
 - **WHEN** a neutral control or nested component needs default, hover, or active differentiation
 - **THEN** it uses the applicable `--rd-gray-100`, `--rd-gray-200`, or `--rd-gray-300` level
 
+#### Scenario: Contributor chooses a component border
+
+- **WHEN** a neutral component border needs default, hover, or active differentiation
+- **THEN** it uses the applicable `--rd-gray-400`, `--rd-gray-500`, or `--rd-gray-600` level
+
+#### Scenario: Contributor chooses a high-contrast component background
+
+- **WHEN** a neutral high-contrast component needs default or hover differentiation
+- **THEN** it uses `--rd-gray-700` or `--rd-gray-800`, respectively
+
+#### Scenario: Contributor needs a translucent gray
+
+- **WHEN** a numbered gray role must allow the underlying surface to show through
+- **THEN** it uses the corresponding `--rd-gray-alpha-*` level
+
 #### Scenario: Contributor chooses text color
 
 - **WHEN** primary or secondary text or an icon renders on a supported neutral background

scripts/helpers/page-helpers.js

@@ -65,6 +65,34 @@ hexo.extend.helper.register("getCategoryTree", function (categories) {
 	return roots;
 });
 
+hexo.extend.helper.register("getCategoryPaths", function (categories) {
+	const items = [];
+	categories?.forEach((category) => items.push(category));
+
+	const nodes = items.map((category) => ({
+		id: String(category._id),
+		parentId: category.parent ? String(category.parent) : null,
+		name: category.name,
+		path: category.path,
+	}));
+	const nodesById = new Map(nodes.map((node) => [node.id, node]));
+	const parentIds = new Set(
+		nodes.map((node) => node.parentId).filter((id) => nodesById.has(id)),
+	);
+
+	return nodes.filter((node) => !parentIds.has(node.id)).map((leaf) => {
+		const categoryPath = [];
+		let current = leaf;
+
+		while (current) {
+			categoryPath.unshift({ name: current.name, path: current.path });
+			current = current.parentId ? nodesById.get(current.parentId) : null;
+		}
+
+		return categoryPath;
+	});
+});
+
 hexo.extend.helper.register("resolvePageKind", function (page) {
 	if (this.is_home()) return "home";
 	if (this.is_post()) return "post";

styles/base/variables.css

@@ -26,10 +26,23 @@
     --rd-gray-100: #f7f7f8;
     --rd-gray-200: #f2f3f4;
     --rd-gray-300: #eef0f2;
-    --rd-gray-alpha-400: rgb(0 0 0 / 10%);
-    --rd-gray-800: #778084;
+    --rd-gray-400: #e4e7e9;
+    --rd-gray-500: #d8dcde;
+    --rd-gray-600: #c7cccf;
+    --rd-gray-700: #a4abad;
+    --rd-gray-800: #7d8689;
     --rd-gray-900: #5c6669;
     --rd-gray-1000: #343a3c;
+    --rd-gray-alpha-100: rgb(0 0 0 / 3%);
+    --rd-gray-alpha-200: rgb(0 0 0 / 5%);
+    --rd-gray-alpha-300: rgb(0 0 0 / 6%);
+    --rd-gray-alpha-400: rgb(0 0 0 / 10%);
+    --rd-gray-alpha-500: rgb(0 0 0 / 14%);
+    --rd-gray-alpha-600: rgb(0 0 0 / 20%);
+    --rd-gray-alpha-700: rgb(0 0 0 / 34%);
+    --rd-gray-alpha-800: rgb(0 0 0 / 48%);
+    --rd-gray-alpha-900: rgb(0 0 0 / 61%);
+    --rd-gray-alpha-1000: rgb(0 0 0 / 78%);
     --scrollbar-color: #c1c1c1;
     --scrollbar-color-hover: #a1a1a1;
     --scroll-bar-bg-color: #fafafa;
@@ -52,10 +65,23 @@
     --rd-gray-100: #27282c;
     --rd-gray-200: #2a2c30;
     --rd-gray-300: #2d2f34;
-    --rd-gray-alpha-400: rgb(255 255 255 / 8%);
-    --rd-gray-800: #778084;
+    --rd-gray-400: #35373c;
+    --rd-gray-500: #41434a;
+    --rd-gray-600: #50525b;
+    --rd-gray-700: #656772;
+    --rd-gray-800: #7c7d89;
     --rd-gray-900: #9595a2;
     --rd-gray-1000: #cbcbd1;
+    --rd-gray-alpha-100: rgb(255 255 255 / 3%);
+    --rd-gray-alpha-200: rgb(255 255 255 / 5%);
+    --rd-gray-alpha-300: rgb(255 255 255 / 6%);
+    --rd-gray-alpha-400: rgb(255 255 255 / 8%);
+    --rd-gray-alpha-500: rgb(255 255 255 / 16%);
+    --rd-gray-alpha-600: rgb(255 255 255 / 23%);
+    --rd-gray-alpha-700: rgb(255 255 255 / 33%);
+    --rd-gray-alpha-800: rgb(255 255 255 / 43%);
+    --rd-gray-alpha-900: rgb(255 255 255 / 54%);
+    --rd-gray-alpha-1000: rgb(255 255 255 / 77%);
     --scrollbar-color: #898989;
     --scrollbar-color-hover: #a1a1a1;
     --scroll-bar-bg-color: #2a2c30;
@@ -69,6 +95,6 @@
     --note-type-title-bg: #4e3a1e;
     --note-black-title-bg: #1e1e1e;
     --note-purple-title-bg: #4e1e4e;
-    --rd-shadow: 0 6px 24px rgb(0 0 0 / 25%);
+    --rd-shadow: 0 6px 24px rgb(0 0 0 / 15%);
   }
 }