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	W3C DTCG JSON, Style Dictionary v4
Testing	Vitest, React Testing Library, axe-core (addon-a11y)

Getting started

Prerequisites

• Node.js 22+

Install and run

npm install
npm run build:tokens   # generate CSS variables + TypeScript constants from token JSON
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
  tokens/
    base.json           # primitive color, spacing, typography tokens (W3C DTCG)
    semantic.json       # semantic aliases referencing base tokens
  scripts/
    build-tokens.ts     # Style Dictionary build script
  src/
    tokens/
      variables.css     # auto-generated CSS custom properties (do not edit)
      tokens.ts         # auto-generated TypeScript constants (do not edit)
    styles/
      tailwind.css      # Tailwind v4 @theme configuration
      global.css        # global styles and font-face declarations
    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 follow the W3C Design Token Community Group (DTCG) format and live in tokens/.

Pipeline:

tokens/base.json + tokens/semantic.json
  -> Style Dictionary v4 (scripts/build-tokens.ts)
  -> src/tokens/variables.css   (CSS custom properties)
  -> src/tokens/tokens.ts       (TypeScript constants)

Semantic tokens reference base tokens using {color.purple.700} syntax.

Adding or modifying tokens

1. Edit tokens/base.json (primitives) or tokens/semantic.json (aliases).
2. Run npm run build:tokens to regenerate the output files.
3. If you added a new color scale, also add matching entries to src/styles/tailwind.css under the @theme block so Tailwind utility classes are available.

Do not edit src/tokens/variables.css or src/tokens/tokens.ts directly -- they are overwritten on every build.

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 referencing design token CSS custom properties (e.g., bg-[var(--color-action-primary)]). 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

1. Create src/components/YourComponent/YourComponent.tsx. Wrap the appropriate React Aria primitive, apply token-based Tailwind classes.
2. Create YourComponent.stories.tsx with a default meta, individual variant stories, a playground story, and at least one play function interaction test.
3. Create YourComponent.test.tsx covering rendering, user interaction, disabled/error states, and keyboard accessibility.
4. 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 tokens/base.json 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 build:tokens	Generate CSS and TypeScript from token JSON
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 licensing@slash-m.com for terms.

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