Conscia Design System

The shared React component library for clear, consistent, and accessible Conscia product experiences.

@conscia-labs/design-system provides semantic design tokens, reusable primitives, and product patterns for operational applications.

Package: available publicly as @conscia-labs/design-system.

Current release: 1.7.4 is the latest stable v1 release.

Documentation: browse the live design system for the complete component reference, examples, and usage guidance.

Install

pnpm add @conscia-labs/design-system

The package requires React 19 and React DOM 19. Tailwind CSS 4 is optional for consumers that use the Tailwind integration.

Quick start

Import public components from the package root:

import {
  Button,
  Field,
  FieldDescription,
  FieldLabel,
  Input,
} from "@conscia-labs/design-system";

export function ConnectionForm() {
  return (
    <form className="grid gap-5">
      <Field>
        <FieldLabel htmlFor="connection-name">Name</FieldLabel>
        <Input id="connection-name" name="name" />
        <FieldDescription>Use a name operators will recognize.</FieldDescription>
      </Field>
      <Button type="submit">Create connection</Button>
    </form>
  );
}

Use the component reference for complete anatomy, options, states, and examples.

Styles and preferences

Tailwind CSS 4 applications import the integration once from their global stylesheet:

@import "tailwindcss";
@import "@conscia-labs/design-system/tailwind.css";

Applications that do not run Tailwind should use the precompiled bundle instead:

@import "@conscia-labs/design-system/standalone.css";

Do not import standalone.css in a Tailwind application. Its preflight and utilities would compete with the application's generated CSS.

Set shared appearance and density preferences on the document root:

<html
  lang="en"
  data-appearance="system"
  data-density="comfortable"
  suppressHydrationWarning
>

Appearance values are light, dark, and system. Density values are comfortable, compact, and operational.

Set data-mood to make a page feel more open. Density sets how much fits; mood sets the spacing, corners, borders, and type around it. With no attribute you get the current bordered look. balanced drops card borders and shadows, rounds corners, and enlarges titles and metric values; it works as an app-wide default. airy goes further, with pill buttons, filled fields, and taller rows, for overview pages, onboarding, empty states, and short settings pages. Put it on the root, or on a subtree that also sets bg-canvas:

<main data-mood="airy" className="bg-canvas">

A mood wins over a density preset on the same element. Keep the current look with operational density for the workbench, logs, and long tables.

On the root, a mood also restyles the AppShell sidebar, through three options that each follow the mood while left at auto:

<AppShell sidebarLayout="auto">            {/* auto | flush | floating */}
  <AppSidebar variant="auto" activeStyle="auto"> {/* variant: auto | light | dark | brand; activeStyle: auto | tint | solid */}

Under a mood, auto floats the sidebar, turns it burgundy, and gives the active item a brighter fill (balanced) or a solid pill (airy). Set any option explicitly to keep it the same in every mood.

AppShell headerLayout="auto" lets the header follow the mood too. Without a mood the header runs across the top (integrated); under balanced or airy the sidebar runs the full height with the brand at its top, and the header turns transparent in the content column until the page scrolls (split). See Shell and navigation.

Use semantic Conscia tokens and utilities rather than copying palette values into an application. See the foundation documentation for the token contract.

Conscia burgundy is the primary identity surface: pair bg-brand with text-brand-foreground. Use brand-accent for blue emphasis and brand-supporting-* for restrained green expression. The low-level palette variables preserve the official colors, while semantic blue and green roles adapt where dark-mode contrast requires it.

Choose the right level

• Use patterns for recurring product workflows such as application shells, page composition, data tables, dashboards, resource details, and workbenches.
• Use primitives for application-specific compositions such as buttons, fields, inputs, selects, dialogs, sheets, tabs, tables, badges, and states.
• Keep routing, authentication, permissions, data fetching, mutations, and business-specific validation in the product application.

The pattern catalog, component catalog, and machine-readable inventory cover the complete public surface.

Public entrypoints

@conscia-labs/design-system            Components and public composition
@conscia-labs/design-system/charts     Recharts-based charts (optional peer: recharts, react-is)
@conscia-labs/design-system/foundation Semantic tokens and foundation exports
@conscia-labs/design-system/patterns   Reusable product patterns
@conscia-labs/design-system/primitives Primitive components and anatomy
@conscia-labs/design-system/utils       Shared utilities

The charts entry is opt-in. Install its peers only in applications that draw charts, and the rest of the package keeps working without them:

pnpm add recharts react-is

This is the beginning of the README. Read the rest at the original. Read the full README ↗