@conscia-labs/design-system 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Conscia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,488 @@
+# Conscia Design System
+
+The shared React component library for building clear, consistent, and accessible Conscia product experiences.
+
+`@conscia-labs/design-system` brings Conscia’s visual foundation, reusable interface primitives, and common product patterns together in one package. It is designed for operational applications where information density, predictable interaction, and accessibility matter.
+
+> **Package:** available publicly as [`@conscia-labs/design-system`](https://www.npmjs.com/package/@conscia-labs/design-system).
+
+## Why this package exists
+
+Conscia products share more than colors and buttons. They share expectations about how navigation works, how data is presented, how status is communicated, and how users move through operational workflows.
+
+This package provides one executable source of truth for those decisions:
+
+```text
+Foundation tokens
+      ↓
+Conscia primitives
+      ↓
+Reusable product patterns
+      ↓
+Conscia applications
+```
+
+Use the design system to:
+
+- Build new Conscia product interfaces.
+- Keep existing products visually and behaviorally consistent.
+- Reuse accessible controls instead of recreating them per application.
+- Compose common shells, resource lists, detail views, tables, and state views.
+- Apply light, dark, and density preferences through shared semantic tokens.
+
+Product applications remain responsible for routing, authentication, permissions, data fetching, mutations, validation, and business-specific behavior.
+
+## What is included
+
+### Foundation
+
+Semantic CSS variables for:
+
+- Light and dark appearance.
+- Comfortable and compact density.
+- Typography, spacing, radius, and elevation.
+- Canvas, surface, border, and text roles.
+- Brand, selection, information, success, warning, and danger semantics.
+
+### Primitives
+
+Reusable interface building blocks composed from React, Radix UI, and ShadCN conventions:
+
+- Alert
+- Avatar
+- Badge
+- Button
+- Card
+- Checkbox
+- Collapsible
+- Dialog
+- Dropdown menu
+- Field and form controls
+- Input and textarea
+- Select and searchable select
+- Sheet
+- Skeleton
+- Switch
+- Table
+- Tabs and navigation tabs
+- Tooltip
+
+### Patterns
+
+Higher-level compositions for recurring product workflows:
+
+- Application shell and sidebar
+- Sidebar navigation
+- Page frame, header, and toolbar
+- Data table and pagination
+- Resource summaries and detail sections
+- Confirmation dialogs
+- Empty, loading, and error states
+- Activity lists and metric bands
+- Code blocks and value meters
+
+## Quick start
+
+### 1. Install the package
+
+Using pnpm:
+
+```bash
+pnpm add @conscia-labs/design-system
+```
+
+Using npm:
+
+```bash
+npm install @conscia-labs/design-system
+```
+
+The package targets React 19 and ships as modern ESM with TypeScript
+declarations. The supported application integration requires Tailwind CSS v4.
+The package declares Tailwind v4 as an optional peer so non-Tailwind consumers
+can use the separate standalone stylesheet without installing Tailwind.
+
+### 2. Load Tailwind and the design-system integration
+
+Import both once in your application’s global stylesheet:
+
+```css
+@import "tailwindcss";
+@import "@conscia-labs/design-system/tailwind.css";
+```
+
+`tailwind.css` imports the design tokens, theme registration, variants,
+keyframes, base rules, and bespoke component CSS. It also contains a
+package-relative `@source` for the published JavaScript, so the application’s
+Tailwind compiler generates the utilities used by both the application and the
+design system in one cascade. Do not add a separate `node_modules` source path.
+
+The deprecated `styles.css` export remains as a foundation-only compatibility
+alias. It does not contain preflight or generated utilities.
+
+### Non-Tailwind applications
+
+Applications that do not run Tailwind can opt into the complete precompiled
+bundle:
+
+```css
+@import "@conscia-labs/design-system/standalone.css";
+```
+
+Tailwind applications must not import `standalone.css`, because its preflight
+and generic utilities would compete with the application’s generated CSS.
+
+### 3. Set the root appearance and density
+
+Apply the default preferences to the root document element:
+
+```tsx
+export function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html
+      lang="en"
+      data-appearance="system"
+      data-density="comfortable"
+      suppressHydrationWarning
+    >
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+Supported values:
+
+| Preference | Values |
+| --- | --- |
+| `data-appearance` | `light`, `dark`, `system` |
+| `data-density` | `comfortable`, `compact` |
+
+Comfortable density is the default for general product interfaces. Compact density is intended for high-volume operational workflows such as inventories and data-heavy administration.
+
+### 4. Use a component
+
+```tsx
+import {
+  Button,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  Field,
+  FieldDescription,
+  FieldLabel,
+  Input,
+} from "@conscia-labs/design-system";
+
+export function CreateConnectionCard() {
+  return (
+    <Card className="max-w-lg">
+      <CardHeader>
+        <CardTitle>Create connection</CardTitle>
+        <CardDescription>
+          Connect a provider to make its resources available to Conscia.
+        </CardDescription>
+      </CardHeader>
+
+      <CardContent>
+        <form className="grid gap-5">
+          <Field>
+            <FieldLabel htmlFor="connection-name">Name</FieldLabel>
+            <Input
+              id="connection-name"
+              name="name"
+              placeholder="Production connection"
+            />
+            <FieldDescription>
+              Use a name that helps operators identify this connection.
+            </FieldDescription>
+          </Field>
+
+          <Button type="submit">Create connection</Button>
+        </form>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+## Building an application shell
+
+The shared shell owns presentation and responsive behavior. The host application supplies routes, links, user context, and actions.
+
+```tsx
+import {
+  AppShell,
+  AppSidebar,
+  AppSidebarContent,
+  AppSidebarHeader,
+  MainRegion,
+  PageContent,
+  PageFrame,
+  PageHeader,
+  ProductIdentity,
+  SidebarTrigger,
+  TopBar,
+} from "@conscia-labs/design-system";
+
+export function ProductShell({
+  navigation,
+  children,
+}: {
+  navigation: React.ReactNode;
+  children: React.ReactNode;
+}) {
+  return (
+    <AppShell>
+      <AppSidebar>
+        <AppSidebarHeader>
+          <ProductIdentity
+            label="Conscia"
+            description="Administration"
+          />
+        </AppSidebarHeader>
+        <AppSidebarContent>{navigation}</AppSidebarContent>
+      </AppSidebar>
+
+      <MainRegion>
+        <TopBar>
+          <SidebarTrigger />
+        </TopBar>
+
+        <PageFrame width="wide">
+          <PageContent>
+            <PageHeader
+              title="Connections"
+              description="Manage provider connections and their availability."
+            />
+            {children}
+          </PageContent>
+        </PageFrame>
+      </MainRegion>
+    </AppShell>
+  );
+}
+```
+
+## Choosing the right component
+
+### Table or DataTable?
+
+Use `Table` for small, bounded, read-only relationships.
+
+Use `DataTable` when an operational inventory needs one or more of:
+
+- Sorting
+- Pagination
+- Row selection
+- Row actions
+- Clickable rows
+- Dedicated mobile rendering
+
+Applications own filters, URL state, API requests, and permissions. When data is paginated by a server, enable manual sorting and manual pagination together so a single downloaded page is never presented as a completely sorted dataset.
+
+### Tabs or NavigationTabs?
+
+Use `Tabs` when content panels change in place without navigation.
+
+```tsx
+<Tabs defaultValue="overview">
+  <TabsList>
+    <TabsTrigger value="overview">Overview</TabsTrigger>
+    <TabsTrigger value="activity">Activity</TabsTrigger>
+  </TabsList>
+  <TabsContent value="overview">...</TabsContent>
+  <TabsContent value="activity">...</TabsContent>
+</Tabs>
+```
+
+Use `NavigationTabs` for route-backed sections. The active destination is represented with `aria-current="page"`.
+
+```tsx
+<NavigationTabs aria-label="Connection sections">
+  <NavigationTabsList>
+    <NavigationTab href="/connections/123" active>
+      Overview
+    </NavigationTab>
+    <NavigationTab href="/connections/123/activity">
+      Activity
+    </NavigationTab>
+  </NavigationTabsList>
+</NavigationTabs>
+```
+
+### Select or SearchableSelect?
+
+Use `Select` for short, familiar option lists.
+
+Use `SearchableSelect` when users need to find an item in a longer list by label, description, or keywords.
+
+Both `FormSelect` and `SearchableSelect` contribute a named value to a native
+HTML form when their `name` prop is provided.
+
+## Semantic color
+
+Color communicates meaning rather than palette choice:
+
+| Role | Purpose |
+| --- | --- |
+| `brand` | Conscia identity and signature moments |
+| `brand-secondary` | Supporting brand expression |
+| `primary` | The primary next action |
+| `selection-*` | Current selection or active destination |
+| `information-*` | Informational messages and evidence |
+| `success-*` | Healthy, verified, approved, or completed states |
+| `warning-*` | Conditions requiring attention |
+| `danger-*` | Destructive actions, failures, and critical states |
+| `neutral-*` | Decoration and non-semantic surfaces |
+
+Do not use success styling merely because something is enabled or active. Success should communicate positive operational evidence.
+
+## Customizing tokens
+
+Override semantic variables after importing the package stylesheet:
+
+```css
+@import "tailwindcss";
+@import "@conscia-labs/design-system/tailwind.css";
+
+:root {
+  --ds-space-page: 3rem;
+  --ds-radius-surface: 0.625rem;
+}
+```
+
+Prefer semantic variables over component-specific descendant selectors. This keeps appearance and density behavior consistent across primitives and patterns.
+
+## Accessibility
+
+Accessibility is part of the component contract:
+
+- Radix-backed components provide keyboard interaction and focus management.
+- Route-backed navigation uses semantic links and `aria-current`.
+- Dialogs and sheets provide labelled modal structure.
+- Form controls expose native labelling and validation attributes.
+- Motion is reduced when the user requests `prefers-reduced-motion`.
+- Semantic status colors are designed to be accompanied by text, icons, or labels.
+
+Applications are still responsible for meaningful labels, heading order, form error relationships, alternative text, and accessible business workflows.
+
+## Framework notes
+
+### Next.js
+
+Import the application global stylesheet from the root layout:
+
+```tsx
+import "./globals.css";
+```
+
+The component entries are explicit client-only boundaries, while server-safe
+code is published separately. For example, React Server Components should
+import `cn` from `@conscia-labs/design-system/utils`. The package does not need
+`transpilePackages`; Next.js will establish a client boundary for component
+exports.
+
+### Other React applications
+
+The primitives are router-independent and can be used with Vite or other
+ESM-capable React build systems. Route-backed patterns accept
+application-supplied links rather than depending on Next.js navigation.
+
+### Focused imports
+
+The root package is the simplest import path. Public subpath exports are also
+available when an application wants a more explicit dependency boundary:
+
+```tsx
+import { Button } from "@conscia-labs/design-system/primitives";
+import { DataTable } from "@conscia-labs/design-system/patterns";
+import {
+  applyConsciaPreferences,
+} from "@conscia-labs/design-system/foundation";
+import { cn } from "@conscia-labs/design-system/utils";
+```
+
+All public entry points are ESM-only.
+
+## Local development
+
+Install dependencies:
+
+```bash
+pnpm install
+```
+
+Run the playground:
+
+```bash
+pnpm dev:playground
+```
+
+The playground is available at [http://localhost:3020](http://localhost:3020).
+
+Run the project checks:
+
+```bash
+pnpm lint
+pnpm lint:playground
+pnpm typecheck
+pnpm typecheck:playground
+pnpm test
+pnpm test:package
+pnpm build:playground
+```
+
+`pnpm test:package` creates the production artifacts, validates the package
+manifest, and imports the package through its public export map. The npm
+`prepack` hook runs the same gate before a tarball can be produced.
+
+Reusable foundation, primitive, and pattern code belongs in `src`. Fixtures and visual documentation belong in `playground`.
+
+## Releasing
+
+Releases are published from GitHub Actions through npm trusted publishing. The
+release tag must exactly match the version in `package.json`.
+
+For example, to publish the next patch:
+
+```bash
+pnpm version patch --no-git-tag-version
+git add package.json
+git commit -m "Release v0.2.1"
+git tag -a v0.2.1 -m "Release v0.2.1"
+git push origin main
+git push origin v0.2.1
+```
+
+Pushing the tag starts the `npm-production` release workflow. The
+workflow verifies the tag, runs the package tests, builds the publishable
+artifacts, and publishes without a long-lived npm token.
+
+## Design-system boundaries
+
+Add something to this package when it:
+
+- Is shared by multiple Conscia products or workflows.
+- Encodes a reusable visual or interaction convention.
+- Can remain independent of product permissions, APIs, and domain state.
+- Has a stable, accessible public interface.
+
+Keep something in the product application when it:
+
+- Fetches or mutates product data.
+- Depends on route definitions or authorization rules.
+- Contains product-specific validation or secret handling.
+- Represents a one-off business workflow.
+
+This boundary keeps the design system reusable without turning it into a second application framework.
+
+## License
+
+Released under the [MIT License](./LICENSE).

package/dist/card-DqFHjLjm.d.ts

@@ -0,0 +1,22 @@
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import * as React from 'react';
+import { VariantProps } from 'class-variance-authority';
+import * as SeparatorPrimitive from '@radix-ui/react-separator';
+
+declare const buttonVariants: (props?: ({
+    variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | null | undefined;
+    size?: "default" | "sm" | "lg" | "icon" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+declare function Button({ className, variant, size, asChild, type, ...props }: React.ComponentProps<"button"> & VariantProps<typeof buttonVariants> & {
+    asChild?: boolean;
+}): React.JSX.Element;
+
+declare function Separator({ className, orientation, decorative, ...props }: React.ComponentProps<typeof SeparatorPrimitive.Root>): React.JSX.Element;
+
+declare function Card({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function CardHeader({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function CardTitle({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function CardDescription({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function CardContent({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+
+export { Button as B, Card as C, Separator as S, CardContent as a, CardDescription as b, CardHeader as c, CardTitle as d, buttonVariants as e };