Mycelia Design System

A React component library built with React Aria Components and vanilla-extract.

Features

• Accessible by default - Built on React Aria Components for full WCAG compliance
• Type-safe tokens - Design tokens available as TypeScript values or vanilla-extract theme contracts
• Figma aligned - Tokens and components match the Mycelia Figma Design System

Installation

npm install @ecologi-action-ltd/mycelia

Typography

Mycelia uses Hanken Grotesk as its primary typeface. Add this to your HTML <head>:

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Hanken+Grotesk:wght@400;500;600;700&display=swap" rel="stylesheet">

Or import in your CSS:

@import url('https://fonts.googleapis.com/css2?family=Hanken+Grotesk:wght@400;500;600;700&display=swap');

Setup

1. Import styles

Import the CSS file in your app's entry point:

import '@ecologi-action-ltd/mycelia/styles.css';

2. Apply the theme

Add the theme class to your root element. Import it from @ecologi-action-ltd/mycelia/theme:

import { myceliaTheme } from '@ecologi-action-ltd/mycelia/theme';

// In your root layout/component
<body className={myceliaTheme}>
  {children}
</body>

Next.js App Router

For Next.js App Router, your layout.tsx should look like:

import '@ecologi-action-ltd/mycelia/styles.css';
import { myceliaTheme } from '@ecologi-action-ltd/mycelia/theme';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <link rel="preconnect" href="https://fonts.googleapis.com" />
        <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
        <link
          href="https://fonts.googleapis.com/css2?family=Hanken+Grotesk:wght@400;500;600;700&display=swap"
          rel="stylesheet"
        />
      </head>
      <body className={myceliaTheme}>
        {children}
      </body>
    </html>
  );
}

Client-side routing

For Link components to work with client-side navigation, wrap your app with RouterProvider. This is exported from a separate entry point to avoid requiring "use client" in server components.

For full details, see the React Aria routing documentation.

Next.js App Router example

Create a client provider component:

// app/providers.tsx
"use client";

import { RouterProvider } from '@ecologi-action-ltd/mycelia/router';
import { useRouter } from 'next/navigation';

export function Providers({ children }: { children: React.ReactNode }) {
  const router = useRouter();
  return <RouterProvider navigate={router.push}>{children}</RouterProvider>;
}

Then use it in your layout:

// app/layout.tsx
import '@ecologi-action-ltd/mycelia/styles.css';
import { myceliaTheme } from '@ecologi-action-ltd/mycelia/theme';
import { Providers } from './providers';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body className={myceliaTheme}>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

3. Use components

import { Button, Text } from '@ecologi-action-ltd/mycelia';

<Text variant="h1">Welcome to Mycelia</Text>
<Button variant="primary">Get Started</Button>

Using Tokens

Tokens can be used directly in your own styles without vanilla-extract:

import { tokens } from '@ecologi-action-ltd/mycelia/tokens';

const styles = {
  backgroundColor: tokens.color.surface.primary.default,
  borderRadius: tokens.radius.md,
  padding: tokens.spacing['16'],
};

For vanilla-extract users, use the theme contract for type-safe CSS variable access:

import { vars } from '@ecologi-action-ltd/mycelia/theme';
import { style } from '@vanilla-extract/css';

export const card = style({
  backgroundColor: vars.color.surface.primary.default,
  borderRadius: vars.radius.md,
});

Documentation

Run Storybook to explore all components and tokens:

npm run storybook

Development

See CONTRIBUTING.md for development setup and adding new components.

Releasing

This project uses Changesets for version management and releases.

Adding a changeset

When making changes that should be released, create a changeset:

npm run changeset

This will prompt you to:

1. Select the type of change (patch, minor, major)
2. Write a summary of the changes

A markdown file will be created in .changeset/ - commit this with your PR.

When to add a changeset

• patch: Bug fixes, documentation updates
• minor: New features, non-breaking changes
• major: Breaking changes

Skip changesets for internal changes like CI updates or refactors that don't affect the public API.

How releases work

1. PRs with changesets are merged to main
2. A "Version Packages" PR is automatically created/updated
3. When the Version PR is merged, the package is published to npm

Testing PR changes

PR preview packages are automatically published. Install them via the link in the PR comments:

npm i https://pkg.pr.new/@ecologi-action-ltd/mycelia@<commit-hash>

License

MIT