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

1. Edit src/styles/theme.css directly.
2. If adding a new color scale, add entries in all four sections (primitives, light semantics, dark semantics, @theme inline).
3. 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

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 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.