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
The package also exports tailwind.css, standalone.css, foundation.css,
styles.css (compatibility), agent-guide.md, agent-manifest.json, and
package.json.
Accessibility and composition
Interactive controls require an accessible name, visible focus, and keyboard
behavior appropriate to their role. Use the documented field anatomy for labels,
descriptions, and errors. When a popup is nested inside a modal surface, use the
documented modal={false} option where supported.
The library uses Base UI internally for behavior-heavy components. Consumers
should import the design-system API and should not install Base UI, Radix, or
copied shadcn component source to reproduce its internals.
Upgrading to v1
Version 1 is a clean API and implementation break. Component concepts and public
names remain recognizable, but old Radix/shadcn implementation details are not
part of the contract:
- Use the documented
render prop instead of the removed asChild API.
- Use Conscia semantic token roles instead of legacy utilities such as
bg-primary, bg-muted, and border-input.
- Do not add
@base-ui/react, @radix-ui/*, or copied shadcn components to the
application.
- Recheck dialogs, sheets, menus, selects, forms, tables, and icon-only actions
against the application's keyboard and accessibility tests.
Read the complete v1 migration guide
for the API and application-owner runbook.
Agent support
Install the package-local guidance into an application's AGENTS.md:
pnpm exec conscia-design-system init-agents
Preview the managed block without writing a file:
pnpm exec conscia-design-system init-agents --dry-run
The installed AGENT_GUIDE.md
is version-matched to the package. The live playground also publishes
llms.txt and the
agent manifest.
Documentation and maintenance
The repository's playground contains the executable documentation site. Run it
locally with pnpm dev:playground; the static site is published to GitHub Pages
by the version-tag release workflow.
License
MIT
