Orfium Ictinus

A comprehensive design system and UI component library for Orfium products

This monorepo contains the Orfium Design System - an opinionated UI kit library providing unified, cross-product UX, UI, and accessibility standards.

Repository Structure

This is a monorepo managed with Turbo and pnpm:

orfium-ictinus/
├── apps/
│   └── storybook/          # Storybook documentation and component showcase
├── packages/
│   └── ictinus/            # Main design system package (@orfium/ictinus)

Packages

• @orfium/ictinus - The main design system package containing all UI components, themes, tokens, and utilities
• @orfium/tokens - A dedicated package containing the design system tokens for external system usage

Apps

• Storybook - Interactive documentation and component playground

Prerequisites

• Node.js >= 24
• pnpm >= 11

Quick Start

1. Clone the repository

   git clone https://github.com/Orfium/orfium-ictinus.git
   cd orfium-ictinus

2. Install dependencies

   pnpm install

3. Start development servers

   # Start all development servers (Storybook, etc.)
   pnpm dev
   
   # Or start Storybook specifically
   pnpm --filter storybook dev

4. Build all packages

   pnpm build

Available Scripts

Script	Description
pnpm dev	Start all development servers
pnpm build	Build all packages and apps
pnpm test	Run all tests
pnpm test:coverage	Run tests with coverage
pnpm lint	Run linting across all packages
pnpm check	Run all checks (TypeScript, linting, formatting)
pnpm clean	Remove all node_modules

Testing

We use Vitest for testing:

# Run all tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Generate coverage report
pnpm coverage:report

Documentation

• Storybook - Interactive component documentation (after running pnpm dev)
• Package README - Detailed usage instructions for the design system
• Contribution Guidelines - How to contribute to this project

Using the Design System

For detailed usage instructions, see the Ictinus package README.

Quick example:

import { ThemeProvider } from '@orfium/ictinus';
import { Box, Button, ThemeProvider as VanillaThemeProvider } from '@orfium/ictinus/vanilla';

export function App() {
  return (
    <ThemeProvider>
      <VanillaThemeProvider>
        <Box display="flex" alignItems="start" flexDirection="column">
          <Button>Submit</Button>
        </Box>
      </VanillaThemeProvider>
    </ThemeProvider>
  );
}

Migrating from Emotion to Vanilla CSS

Components are gradually moving from Emotion (@orfium/ictinus) to Vanilla Extract (@orfium/ictinus/vanilla); switch imports per component and keep both theme providers until Ictinus no longer uses Emotion.

Migration & Codemods

The library includes codemods to help migrate between versions:

# Run migration codemods
npx @orfium/ictinus migrate

Available codemods can be found in packages/ictinus/codemods/.

Contributing

We welcome contributions! Please read our Contributing Guidelines before submitting a PR.

Development Workflow

1. Create a feature branch: git checkout -b feature/new-feature
2. Make your changes
3. Run checks: pnpm check
4. Submit a PR with a conventional commit title

PR Guidelines

• Use conventional commit format for PR titles (e.g., feat(Button): add loading state)
• Provide detailed descriptions and screenshots
• Ensure all tests pass
• Update documentation as needed

Versioning & Releases

This project uses Changesets for versioning and releases:

# Create a changeset
pnpm changeset

# Release (CI/CD handles this)
pnpm release

Links

• npm package
• GitHub repository
• Issues

License

Apache-2.0