Zigzag Yang Design System

设计系统全部组件：shadcn 官方 + asanshay / aceternity / cardcn / 8starlabs 注册表

Description List

Code Block

description-list-example.tsx

import { DescriptionList } from "@/components/ui/description-list";

export function ProductInfo() {
  const data = {
    "品牌": "Simplus",
    "型号": "SGS-1200",
    "功率": "1200W",
    "水箱容量": "170ml",
    "预热时间": "10秒",
  };

  return <DescriptionList data={data} />;
}

ASCII Art

图片转 ASCII 字符画。原则：图上不覆盖文字，标题在图片下方排版。对原图要求高（主体突出、轮廓清晰、对比度高），实际使用中多数照片效果不佳，谨慎使用。样图为官方推荐示例（aceternity manu.webp）。

容器宽高比应与源图一致（本样图为方图）——字符网格按图片比例采样，强行撑满版心会横向拉伸失真。

默认约定：无特殊要求时，color 用印记红 var(--color-accent)（必须是 var() 形式，组件只解析 var() 开头的颜色，hsl(var(...)) 会静默失效变黑）、charset 用 standard、默认静态无动画（animated 与 animateOnView 默认均为 false）；需要入场动画时显式传 animated animationStyle="typewriter"。字符画是图片的替代呈现，不是背景——不要在 ASCII 图上覆盖标题或正文。依赖 motion 包。

ASCII Fluid

WebGL 流体字符场：指针拖出墨迹，漩涡量化成字符亮度场，静止时有环境漩涡缓慢游移。定位是整页背景装饰——canvas 自绘纸色底，正文直接浮在字符场上，仍可读。

版心区域（可选遮挡）

默认整页生效；如需只在页边露出，给阅读栏加 bg-background 即可（本演示即此效果）。把指针移到盒内页边拖一拖。

ascii-fluid-background-usage.tsx

import { AsciiFluidBackground } from "@/components/ui/ascii-fluid-background";

// 页面根处挂载一次；整页背景生效——外层容器不得带
// bg-background 等不透明全宽背景（会整体盖住流体层）
<AsciiFluidBackground />
<main className="mx-auto max-w-measure">
  …正文…
</main>

// 可选：只想在版心两侧页边露出时，给阅读栏单独加底色
// <main className="mx-auto max-w-measure bg-background">

默认约定：ink 一律印记红（亮 #E63946 / 暗 #F25160），paper 随主题黑/白（#FFFFFF / #0A0A0A）。组件只解析 hex 颜色（不认 var()/hsl()），由包装层 useAsciiFluidColors() 按 next-themes 解析。全页背景用 AsciiFluidBackground（fixed、-z-10、pointer-events-none、 aria-hidden，依赖 body 背景向 canvas 传播透出）；整页生效的关键是页面外层容器不得带 bg-background 等不透明全宽背景；若只想版心两侧露出，给阅读栏容器单独加 bg-background 遮挡。区块内嵌用 AsciiFluid 直接取色即可。尊重 prefers-reduced-motion。触屏设备（pointer: coarse）自动不渲染——流体是鼠标轨迹交互，触屏无意义且耗电；桌面带触摸屏的混合设备主指针仍是 fine，不受影响。

Cards

三档卡片：Basic（asanshay，六种变体）/ Wide（宽幅导引）/ Product（产品展示）

Basic Card · outline（唯一保留变体）

卡片标题

辅助说明文字

正文内容区域。asanshay 卡片只保留 outline 变体：细边框、无阴影、透明底。

Wide Card · 宽幅导引

本周更新

题库系统新增 3 个数据源；设计系统引入卡片三件套。适合章节导引、公告条、宽幅信息块。

Product Card · 产品展示（hover 浮起信息条）

SGS-1200

1200W · 170ml 水箱 · 10秒预热

Button

Table

Data Table

基于 TanStack Table v9 的数据表格，支持排序、筛选、分页、行选择、列显隐。适合多字段数据库展示场景。

Claude Todo List

类 Claude Code 的任务清单：✔ 完成（删除线）/ ◼ 进行中 / ◻ 待办，适合任务清单式内容

档位	变量	值	适用场景
窄版	--measure-compact	32rem	短文、侧边栏、单列卡片
默认	--measure	40rem	报告、长文、审阅类
宽版	--measure-wide	64rem	表格、表单、双栏布局
极宽	--measure-full	80rem	看板、仪表盘、多栏网格


pending	m@example.com	¥100.00
processing	example@gmail.com	¥125.00
success	ken99@example.com	¥316.00
success	Abe45@example.com	¥242.00
processing	Monserrat44@example.com	¥837.00
success	Silas22@example.com	¥874.00
failed	carmella@example.com	¥721.00
success	john@example.com	¥450.00
pending	jane@example.com	¥99.00
success	bob@example.com	¥620.00

修复版心约束（--container-* 命名空间） (completed)
ASCII Art 首图替换标题区 (completed)
引入卡片三件套 (in progress)
周报自动生成管线 (pending)

Chart

Heatmap

8starlabs 注册表：时间密度热力图（GitHub 贡献图式），支持 discrete / interpolate 两种着色模式与 squares / bubbles 两种形态

Timeline

8starlabs 注册表：时间线组件，分 Horizontal 与 Vertical 两种方向，支持卡片 / 无卡片、交错 / 单侧、实心 / 空心节点

Horizontal · 交错卡片（默认，截取前 3 项以完整落入版心）

2026-08-22
设计系统立项
从 Zigzag Press 分离，Next.js + Tailwind + shadcn/ui 路线确定。
2026-08-22
首个实战报告上线
大兴安岭国庆旅游调研报告构建并发布到 OSS。
2026-08-23
明暗切换全站落地
右上角固定 ThemeToggle，地图瓦片风格自动跟随。

Vertical · 无卡片紧凑（noCards）

2026-08-22
设计系统立项
2026-08-22
首个实战报告上线
2026-08-23
明暗切换全站落地
2026-08-23
版心变量踩坑
2026-08-23
8starlabs 组件入库

Map View

适用场景

组件	适用场景	不适用场景
Description List	产品参数、个人信息、配置项、API 响应	需要复杂交互的表格数据
Code Block	技术文档、API 文档、教程	纯文本报告（无需语法高亮）
ASCII Art	报告首图、章节题图、创意展示（图上不覆盖文字；只适合主体突出、轮廓清晰的图片）	复杂风景、渐变照片、细节丰富的图片
ASCII Fluid	页面/区块背景装饰（版心之外）、着陆页氛围	正文阅读区、无构建链的单文件交付（依赖 WebGL）
Basic Card（outline）	通用内容块、列表项、信息分组	需要强视觉层级对比的卡片区
Wide Card	章节导引、公告条、宽幅信息块	窄栏中的内容卡片
Product Card	产品/作品/书籍封面展示（桌面 hover 交互）	关键信息只藏在 hover 浮层的场景（触屏无 hover）
Button	操作触发、表单提交（7 变体 × 5 尺寸）	—
Table	数据、对比、行程、参数等结构化信息	需要复杂交互（排序/筛选/分页）→ 用 Data Table
Data Table	多字段数据库、可排序筛选分页的数据网格	简单静态对比表（Table 更轻量）
Claude Todo List	任务清单式内容、进度展示、复盘记录	需要交互勾选的真实待办
Chart	趋势、对比、占比等数据可视化	—
Heatmap	时间密度可视化：活跃度、打卡、token 用量等按日分布	精确数值对比（色块不适合读数）
Timeline	里程碑、项目历程、版本记录（横向交错 / 纵向紧凑）	纯流水账长列表（用普通列表更省空间）
Map View	地理位置标注、路线、区域范围展示	纯装饰性插图

组件选型速查（表注在表格横滑时保持固定）

组件效果预览