@cytario/design

中文文档

11.1.3发布于 2026/10/29AGPL-3.0-onlyTypeScriptES Module构建来源已验证近 30 天下载 2778

Cytario design system and brand portal

文档目录14 节

Tech stack
Getting started
Prerequisites
Install and run
Project structure
Design tokens
Adding or modifying tokens
Component development
Approach
Creating a new component
Brand colors
Available components
Scripts
License

cytario design system

Single source of truth for the cytario corporate identity -- from brand foundation (logos, colors, typography) to production-ready React components. Built as an interactive Storybook portal for designers, developers, and stakeholders.

Tech stack

Layer	Technology
Documentation	Storybook 10, MDX
UI framework	React 19, TypeScript 5.9
Styling	Tailwind CSS v4, CSS custom properties
Accessibility	React Aria Components (Adobe)
Design tokens	CSS custom properties (`src/styles/theme.css`)
Testing	Vitest, React Testing Library, axe-core (addon-a11y)

Getting started

Prerequisites

Node.js 22+

Install and run

npm install
npm run dev            # start Storybook at http://localhost:6006

Project structure

cytario-design/
  .storybook/          # Storybook configuration (main.ts, preview.ts, theme.ts)
  assets/
    logos/              # SVG and PNG logo variants (full, reduced, black, white, on-purple)
    fonts/              # Montserrat font files
    approvals/          # approved brand materials
  scripts/
    validate-tokens.ts # CI script to verify dark-theme invariant
  src/
    styles/
      theme.css           # single hand-maintained token file — primitives, light/dark semantics, @theme inline
      tailwind.css        # Tailwind v4 entry point (imports theme.css)
    components/
      Button/           # Button.tsx, Button.stories.tsx, Button.test.tsx
      Input/            # Input.tsx, Input.stories.tsx, Input.test.tsx
      Select/           # Select.tsx, Select.stories.tsx, Select.test.tsx
      Table/            # Table.tsx, Table.stories.tsx, Table.test.tsx
    docs/               # MDX documentation pages (Introduction, Foundation, Guidelines)

Design tokens

Tokens are hand-maintained in src/styles/theme.css — a single CSS file that is the source of truth:

Primitives (:root): raw hex/rgba values (--color-purple-500)
Semantic light (:root): var() refs to primitives (--color-primary: var(--color-purple-500))
Semantic dark ([data-theme="dark"]): overrides for every semantic token
@theme inline: maps tokens to Tailwind v4 utility names

All token CSS lives in @layer cytario-design so consumer app styles can override.

Adding or modifying tokens

Edit src/styles/theme.css directly.
If adding a new color scale, add entries in all four sections (primitives, light semantics, dark semantics, @theme inline).
Run npm run validate:tokens to verify the dark-theme invariant (every :root color has a [data-theme="dark"] counterpart).

Component development

Each component follows the same file structure:

src/components/ComponentName/
  ComponentName.tsx           # implementation
  ComponentName.stories.tsx   # Storybook stories (CSF3)
  ComponentName.test.tsx      # Vitest + React Testing Library tests

Approach

Behavior and accessibility: React Aria Components provide keyboard navigation, ARIA attributes, and focus management out of the box. Components wrap React Aria primitives with cytario styling.
Styling: Tailwind CSS v4 utility classes, including the idiomatic semantic color utilities generated from the design tokens (e.g., bg-primary, text-muted-foreground, bg-destructive). No runtime CSS-in-JS.
Stories: CSF3 format with args, argTypes, and play functions for interaction tests. All stories are automatically checked by the a11y addon (axe-core).
Tests: Vitest with React Testing Library. Test by user perspective -- query by role and label, verify behavior and accessibility attributes. Do not test React Aria internals.

Creating a new component

Create src/components/YourComponent/YourComponent.tsx. Wrap the appropriate React Aria primitive, apply token-based Tailwind classes.
Create YourComponent.stories.tsx with a default meta, individual variant stories, a playground story, and at least one play function interaction test.
Create YourComponent.test.tsx covering rendering, user interaction, disabled/error states, and keyboard accessibility.
Export from a barrel file if one exists, or import directly.

Brand colors

The cytario brand is built on two primary colors:

Color	Hex	Token	Usage
Purple	`#5c2483`	`--color-purple-700` / `--color-brand-primary`	Primary brand color, headings, secondary actions
Teal	`#35b7b8`	`--color-teal-500` / `--color-brand-accent`	Accent color, primary actions, interactive elements

Both colors have a full 50--900 scale defined in src/styles/theme.css for use in hover states, backgrounds, and subtle tints.

Available components

Component	Variants	React Aria primitive
Button	primary, secondary, ghost, destructive (sm/md/lg)	`Button`
Input	text, email, password, number; error + description states	`TextField`
Select	single-select dropdown with search	`Select`
Table	sortable columns, row selection	`Table`

Scripts

Command	Description
`npm run dev`	Start Storybook dev server on port 6006
`npm run build`	Build static Storybook site to `storybook-static/`
`npm run validate:tokens`	Verify dark-theme invariant in token CSS
`npm run build:css`	Build the Tailwind stylesheet to `dist/index.css`
`npm run watch:css`	Rebuild `dist/index.css` on change (keeps running)
`npm test`	Run Vitest test suite (watch mode)
`npx vitest run`	Run tests once (CI mode)
`npm run lint`	Lint `src/` with ESLint

License

This project is dual-licensed:

Open source: GNU Affero General Public License v3.0 (AGPL-3.0-only)
Commercial: A proprietary license is available from Slash-m GmbH for use cases where the AGPL is not suitable. Contact [email protected] for terms.

"cytario" and the cytario logo are trademarks of Slash-m GmbH. See TRADEMARK.md.

版本与发布记录

@cytario/design 共发布 70 个版本，首次发布于 2026/02/22；过去 12 个月发布了 70 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本	发布日期	距今
`11.1.3`latest	2026/10/29	13 天前
`11.1.2`	2026/10/24	18 天前
`11.1.1`	2026/10/23	18 天前
`11.1.0`	2026/10/07	1 个月前
`11.0.2`	2026/09/30	1 个月前
`11.0.1`	2026/09/26	1 个月前

其他发布通道：rc-1 → 0.0.0-development。

关于 @cytario/design 的常见问题

@cytario/design 是什么？

Cytario design system and brand portal

如何安装 @cytario/design？

在项目目录运行 npm install @cytario/design，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（>=18.0.0）、react-dom（>=18.0.0）、@tanstack/react-table（^8.21.3）、react-aria-components（^1.20.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

@cytario/design 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@cytario/design 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module，更早的版本需要改用动态 import()。

@cytario/design 可以商用吗？

@cytario/design 使用 AGPL-3.0-only 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

@cytario/design 的下载量有多少？

根据 npm 官方下载统计，@cytario/design 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,778 次，日均约 93 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@cytario/design 还在维护吗？

最新版本 11.1.3 发布于 2026/10/29（13 天前）；至今共发布 70 个版本，其中过去 12 个月发布了 70 个；首次发布于 2026/02/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

npm install @cytario/design

pnpmpnpm add @cytario/design
yarnyarn add @cytario/design
bunbun add @cytario/design

peer 依赖react >=18.0.0react-dom >=18.0.0@tanstack/react-table ^8.21.3react-aria-components ^1.20.0

npm 7+ 与 pnpm 8+ 会自动安装必需的 peer 依赖，Yarn 需手动安装。

在你的项目目录中运行此命令。

近 30 天下载

2,778

约 2778 次日均 93 次

统计周期 2026/10/11 – 2026/11/09
数据来自 npm 官方下载统计，今天更新

最新版本11.1.3发布于 13 天前

开源许可AGPL-3.0-only网络 Copyleft

包体积5.2 MB37 个文件 · 解压后

运行依赖3 个另有 4 个 peer 依赖

模块格式ES Module

TypeScript自带类型

发布版本70 个近 12 个月 70 个

首次发布2026/02/228 个月前

元数据更新2026/10/29

每一个软件包背后，
都有分享与创造的人。