@conscia-labs/design-system 0.3.5 → 1.0.0

package/README.md

@@ -5,6 +5,10 @@ The shared React component library for building clear, consistent, and accessibl
 `@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).
+>
+> **v1.0.0:** this README documents the clean-break v1 contract. The repository is now preparing the `1.0.0` release candidate for publication through the Phase 8 workflow.
+>
+> **Migration:** upgrading an application to v1? Follow the [Design System v1 Migration Guide](https://github.com/conscia-labs/design-system/blob/main/docs/design-system-v1-migration.md).
 
 ## Why this package exists
 
@@ -32,6 +36,19 @@ Use the design system to:
 
 Product applications remain responsible for routing, authentication, permissions, data fetching, mutations, validation, and business-specific behavior.
 
+## Migrating to v1.0.0
+
+Version `1.0.0` is a clean API and implementation break. Component concepts and
+public names remain recognizable, but Radix and shadcn implementation details
+are no longer part of the contract. In particular:
+
+- Replace `asChild` with the documented `render` prop where custom-host composition is required.
+- Replace legacy token utilities such as `bg-primary`, `bg-muted`, and `border-input` with the canonical Conscia semantic roles documented in the migration guide.
+- Do not add `@base-ui/react`, `@radix-ui/*`, or copied shadcn components to the application; Base UI is bundled and used internally by the design system.
+- Recheck dialogs, sheets, menus, selects, comboboxes, tabs, tooltips, forms, tables, and icon-only actions against the application’s keyboard and accessibility tests.
+
+The complete, agent-readable upgrade runbook is [`docs/design-system-v1-migration.md`](./docs/design-system-v1-migration.md) in this repository. You can also open the [migration guide on GitHub](https://github.com/conscia-labs/design-system/blob/main/docs/design-system-v1-migration.md). The guide is intentionally kept in the repository’s `docs/` directory rather than the npm tarball, so the GitHub link is the durable location for app owners and coding agents.
+
 ## What is included
 
 ### Foundation
@@ -46,12 +63,15 @@ Semantic CSS variables for:
 
 ### Primitives
 
-Reusable interface building blocks composed from React, Radix UI, and ShadCN conventions:
+Reusable Conscia-owned interface building blocks composed from native React
+markup and Base UI behavior where interaction complexity requires it:
 
 - Alert
+- AlertDialog
 - Avatar
 - Badge
 - Button
+- IconButton
 - Card
 - Checkbox
 - Collapsible
@@ -59,13 +79,19 @@ Reusable interface building blocks composed from React, Radix UI, and ShadCN con
 - Dropdown menu
 - Field and form controls
 - Input and textarea
-- Select and searchable select
+- Select, FormSelect, and searchable select
 - Sheet
 - Skeleton
 - Switch
 - Table
 - Tabs and navigation tabs
 - Tooltip
+- Popover
+- Shortcut hint
+- Spinner
+- Avatar group
+- Filter chip
+- Toast provider and viewport
 
 ### Patterns
 
@@ -80,21 +106,75 @@ Higher-level compositions for recurring product workflows:
 - Empty, loading, and error states
 - Activity lists and metric bands
 - Code blocks and value meters
+- Command palette
+- Filter bar
+
+### Supporting interaction patterns
+
+#### Command palette
+
+`CommandPalette` accepts an explicit list of commands, filters labels and
+keywords, and supports keyboard navigation without a global command registry:
+
+```tsx
+import { Button, CommandPalette } from "@conscia-labs/design-system";
+
+<CommandPalette
+  items={[{ id: "settings", label: "Open settings", keywords: ["preferences"] }]}
+  onSelect={(item) => openCommand(item.id)}
+  trigger={<Button variant="outline">Open commands</Button>}
+/>
+```
+
+#### Toasts
+
+Toasts are opt-in. Mount one provider and viewport, then use `useToast` from a
+descendant component:
+
+```tsx
+import {
+  Button,
+  ToastProvider,
+  ToastViewport,
+  useToast,
+} from "@conscia-labs/design-system";
+
+function SaveButton() {
+  const { add } = useToast();
+  return (
+    <Button onClick={() => add({ title: "Saved", variant: "success" })}>
+      Save
+    </Button>
+  );
+}
+
+function App() {
+  return (
+    <ToastProvider>
+      <SaveButton />
+      <ToastViewport />
+    </ToastProvider>
+  );
+}
+```
 
 ## Quick start
 
 ### 1. Install the package
 
+For the v1 release, install the explicit `1.0.0` range after Phase 8 publishes
+the package.
+
 Using pnpm:
 
 ```bash
-pnpm add @conscia-labs/design-system
+pnpm add @conscia-labs/design-system@^1.0.0
 ```
 
 Using npm:
 
 ```bash
-npm install @conscia-labs/design-system
+npm install @conscia-labs/design-system@^1.0.0
 ```
 
 The package targets React 19 and ships as modern ESM with TypeScript
@@ -160,10 +240,31 @@ Supported values:
 | Preference | Values |
 | --- | --- |
 | `data-appearance` | `light`, `dark`, `system` |
-| `data-density` | `comfortable`, `compact` |
+| `data-density` | `comfortable`, `compact`, `operational` |
 
 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.
 
+Operational density is an explicit opt-in preset for interfaces that prioritize
+information throughput and deliberate hierarchy: admin pages, chat shells,
+connectors, catalogs, and Workspace-like surfaces. It tightens the shared type
+scale to approximately 13px body/UI text, 12px metadata, 15–16px section titles,
+and a 26px page title with a 650 weight, `-0.04em` tracking, and `1.08` line
+height. It also tightens reusable spacing and control rhythm while preserving
+the existing touch-target, focus-ring, color, radius, and shadow contracts.
+
+```tsx
+<html data-appearance="system" data-density="operational">
+  {/* admin, chat, catalog, connector, or workspace-like application */}
+</html>
+```
+
+Use comfortable density for general product reading and mixed-purpose pages.
+Use compact density when an existing consumer already depends on its smaller
+layout preset. Use operational density when the interface needs Workspace-like
+hierarchy across shared components. Do not make 13px the global default: that
+would make narrative, setup, and accessibility-critical product surfaces feel
+compressed.
+
 ### 4. Use a component
 
 ```tsx
@@ -271,6 +372,64 @@ export function ProductShell({
 }
 ```
 
+## Building a workbench surface
+
+Workbench patterns provide a reusable composition for applications that need
+global navigation, a contextual rail, a primary work area, and an inspector.
+They own the shell geometry, responsive rail behavior, resource-row rhythm,
+and inspector hierarchy; the host application supplies its routes, data, and
+actions.
+
+```tsx
+import {
+  ResourceRow,
+  ResourceRowContent,
+  ResourceRowIcon,
+  ResourceRowMeta,
+  ResourceRowTitle,
+  WorkbenchInspector,
+  WorkbenchInspectorSection,
+  WorkbenchMain,
+  WorkbenchRail,
+  WorkbenchSection,
+  WorkbenchSectionHeader,
+  WorkbenchShell,
+} from "@conscia-labs/design-system";
+
+export function WorkspaceSurface({ children }: { children: React.ReactNode }) {
+  return (
+    <WorkbenchShell data-density="operational">
+      <WorkbenchRail variant="global">Global navigation</WorkbenchRail>
+      <WorkbenchRail variant="secondary">Contextual navigation</WorkbenchRail>
+      <WorkbenchMain>
+        <WorkbenchSection>
+          <WorkbenchSectionHeader title="Recent conversations" metadata="12" />
+          <ResourceRow as="a" href="/conversations/1">
+            <ResourceRowIcon aria-hidden="true" />
+            <ResourceRowContent>
+              <ResourceRowTitle>Project brief</ResourceRowTitle>
+              <ResourceRowMeta>Updated just now</ResourceRowMeta>
+            </ResourceRowContent>
+          </ResourceRow>
+        </WorkbenchSection>
+        {children}
+      </WorkbenchMain>
+      <WorkbenchInspector>
+        <WorkbenchInspectorSection label="Details">
+          {/* Product-owned metadata and actions */}
+        </WorkbenchInspectorSection>
+      </WorkbenchInspector>
+    </WorkbenchShell>
+  );
+}
+```
+
+Use `WorkbenchMobileToolbar` and `WorkbenchBackdrop` when a contextual rail
+needs an explicit mobile drawer trigger. Keep product-specific content styles
+local, but use the shared workbench tokens and row primitives instead of
+recreating shell widths, inspector padding, focus states, or resource-list
+typography.
+
 ### Typography and font loading
 
 The design system declares the open-source Source Sans 3 variable font as a
@@ -300,6 +459,23 @@ Prefer these tokens over local `clamp()`, pixel, or one-off font-size values.
 Product-specific layout styles may still control wrapping, maximum width, or
 composition when the content requires it.
 
+Operational consumers can use the token-backed `ds-type-*` utilities without
+creating a parallel styling system:
+
+| Role | Utility | Comfortable baseline | Operational intent |
+| --- | --- | --- | --- |
+| Page/display title | `ds-type-page-title`, `ds-type-display-title` | 28px / 56px | 26px / responsive display, 650 weight, tight tracking |
+| Section title | `ds-type-section-title` | 17px | 16px, 650 weight, tighter line-height |
+| Body/UI | `ds-type-body`, `ds-type-ui` | 15px / 14px | 13px with a 1.4–1.5 rhythm |
+| Metadata | `ds-type-metadata` | 13px | 12px supporting context |
+| Menu/eyebrow | `ds-type-menu-item`, `ds-type-menu-label`, `ds-type-eyebrow` | existing compact roles | compact labels with deliberate tracking |
+| Controls | `ds-type-control`, `ds-type-button` | 14px | 13px, with stronger button weight |
+
+The utilities resolve through CSS custom properties, so light and dark themes
+retain the same semantic colors and focus behavior. Applications should use
+the preset and shared utilities for type/rhythm, while keeping product-specific
+composition, data, and layout ownership local.
+
 Sidebar section labels are intentionally smaller than navigation rows and
 slightly more weighted: comfortable density uses a `12px / 600 / 16px`
 contract with restrained tracking, while compact density reduces the size
@@ -317,6 +493,20 @@ lockups, collapsed navigation identity, and other shared brand placements.
 The icon is decorative by default. Add an `aria-label` when the mark conveys
 meaning without adjacent text, and use `className` to control its size.
 
+### BrandWordmark
+
+`BrandWordmark` is the shared no-tagline Conscia lockup. It embeds the supplied
+496×113 vector geometry and uses `currentColor`, so applications do not need
+separate black and white assets or runtime asset paths. The default treatment
+matches `BrandIcon`: foreground in light mode and white in dark mode.
+
+The wordmark is decorative by default. Add an `aria-label` when it is the only
+accessible naming content, and use `className` to control its width.
+
+```tsx
+<BrandWordmark aria-label="Conscia" className="w-36" />
+```
+
 ### Sidebar variants and semantic surfaces
 
 `AppSidebar` keeps the historical dark treatment by default. Consumers that
@@ -336,14 +526,12 @@ an explicitly light sidebar.
 </AppShell>
 ```
 
-The default is intentionally backwards compatible. The sidebar scope exposes
-reusable semantic aliases for its canvas, header, content, hover, active,
-search, footer, text, icon, group label, count, border, and focus-ring roles.
+The sidebar scope exposes reusable semantic roles for its canvas, header,
+content, hover, active, search, footer, text, icon, group label, count,
+border, and focus-ring roles.
 Use the generated utilities such as `bg-sidebar-canvas`,
 `bg-sidebar-hover`, `text-sidebar-primary-text`, and
 `text-sidebar-metadata-text` in shared or application-owned compositions.
-Legacy aliases including `bg-sidebar`, `bg-sidebar-accent`, and
-`text-sidebar-foreground` remain supported.
 
 Form controls and outline buttons use `bg-surface-control`, with
 `bg-surface-control-hover` for the outline hover state. These semantic surfaces
@@ -362,16 +550,16 @@ Dark mode uses a calm charcoal surface ladder rather than a pure-black canvas:
 
 | Role | Token | Dark value |
 | --- | --- | --- |
-| Application canvas | `--background` / `--canvas` | `#17191c` |
-| Standard surface | `--card` / `--surface` | `#1d2024` |
+| Application canvas | `--canvas` | `#17191c` |
+| Standard surface | `--surface` | `#1d2024` |
 | Raised surface and control | `--surface-raised` / `--surface-control` | `#24272c` |
 | Muted and control-hover surface | `--surface-muted` / `--surface-control-hover` | `#282b31` |
-| Floating surface | `--surface-floating` / `--popover` | `#2c2f36` |
+| Floating surface | `--surface-floating` | `#2c2f36` |
 | Overlay surface | `--surface-overlay` | `#31343a` |
 
 The adjacent steps are intentionally close enough for a calm reading
 environment while remaining distinguishable through luminance, borders, and
-elevation. `--foreground` is a soft high-priority text role (`#eff1f4`), while
+elevation. `--text-primary` is a soft high-priority text role (`#eff1f4`), while
 `--text-secondary`, `--text-supporting`, and `--text-muted` step down to
 `#d4d8df`, `#b3bac5`, and `#929aa7`. Use the semantic `bg-surface-*` and
 `text-*` utilities instead of copying these values into an application. The
@@ -480,7 +668,7 @@ Color communicates meaning rather than palette choice:
 | --- | --- |
 | `brand` | Conscia identity and signature moments |
 | `brand-secondary` | Supporting brand expression |
-| `primary` | The primary next action |
+| `action-*` | Primary actions and their hover, active, foreground, and tinted-background roles |
 | `selection-*` | Current selection or active destination |
 | `information-*` | Informational messages and evidence |
 | `success-*` | Healthy, verified, approved, or completed states |
@@ -510,7 +698,7 @@ Prefer semantic variables over component-specific descendant selectors. This kee
 
 Accessibility is part of the component contract:
 
-- Radix-backed components provide keyboard interaction and focus management.
+- Base UI-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.
@@ -593,23 +781,45 @@ Reusable foundation, primitive, and pattern code belongs in `src`. Fixtures and
 
 ## Releasing
 
-Releases are published from GitHub Actions through npm trusted publishing. The
-release tag must exactly match the version in `package.json`.
+The `1.0.0` release is the first public v1 package. Releases are published from
+GitHub Actions through npm trusted publishing, with the release tag required to
+match the version in `package.json` exactly. npm’s trusted-publishing flow
+provides short-lived CI authentication and provenance for the published
+package.
+
+Before creating the v1 release tag, complete the release checklist in the
+[migration ledger](./docs/base-ui-migration.md), finalize the
+[app-owner migration guide](./docs/design-system-v1-migration.md), and run the
+full local validation suite:
+
+```bash
+pnpm lint
+pnpm lint:playground
+pnpm typecheck
+pnpm typecheck:playground
+pnpm test
+pnpm test:package
+pnpm test:consumer
+pnpm build:playground
+pnpm test:visual
+```
 
-For example, to publish the next patch:
+Then prepare and tag the release:
 
 ```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"
+pnpm version 1.0.0 --no-git-tag-version
+git add package.json README.md docs/base-ui-migration.md docs/design-system-v1-migration.md
+git commit -m "Release v1.0.0"
+git tag -a v1.0.0 -m "Release v1.0.0"
 git push origin main
-git push origin v0.2.1
+git push origin v1.0.0
 ```
 
-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.
+Pushing the tag starts the `npm-production` release workflow. The workflow
+verifies that `v1.0.0` matches `package.json`, runs the release validation, and
+publishes the package to npm without a long-lived npm token. Because this is a
+scoped public package, the release configuration must retain public access;
+see npm’s [scoped-package publishing guidance](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages/).
 
 ## Design-system boundaries
 

package/dist/card-DmBKqvj_.d.ts

@@ -0,0 +1,49 @@
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import * as React from 'react';
+import { useRender } from '@base-ui/react/use-render';
+import { VariantProps } from 'class-variance-authority';
+
+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;
+type ButtonProps = React.ComponentProps<"button"> & VariantProps<typeof buttonVariants> & {
+    render?: useRender.ComponentProps<"button">["render"];
+};
+declare function Button({ className, variant, size, render, type, ...props }: ButtonProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
+type IconButtonNameProps = {
+    "aria-label": string;
+    "aria-labelledby"?: string;
+} | {
+    "aria-label"?: string;
+    "aria-labelledby": string;
+};
+type IconButtonProps = Omit<ButtonProps, "children" | "size" | "aria-label" | "aria-labelledby"> & IconButtonNameProps & {
+    children: React.ReactNode;
+    size?: "sm" | "default" | "lg";
+};
+declare function IconButton({ className, size, ...props }: IconButtonProps): React.JSX.Element;
+
+declare function Input({ className, type, ...props }: React.ComponentProps<"input">): React.JSX.Element;
+
+type SeparatorProps = React.ComponentProps<"div"> & {
+    decorative?: boolean;
+    orientation?: "horizontal" | "vertical";
+};
+declare function Separator({ className, orientation, decorative, role, ...props }: SeparatorProps): React.JSX.Element;
+
+declare const cardVariants: (props?: ({
+    variant?: "default" | "muted" | "elevated" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+type CardProps = React.ComponentProps<"div"> & VariantProps<typeof cardVariants>;
+declare function Card({ className, variant, ...props }: CardProps): React.JSX.Element;
+type CardHeaderProps = React.ComponentProps<"div"> & {
+    action?: React.ReactNode;
+};
+declare function CardHeader({ action, children, className, ...props }: CardHeaderProps): 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;
+declare function CardFooter({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+
+export { Button as B, Card as C, IconButton as I, Separator as S, type ButtonProps as a, CardContent as b, CardDescription as c, CardFooter as d, CardHeader as e, type CardHeaderProps as f, type CardProps as g, CardTitle as h, type IconButtonProps as i, Input as j, type SeparatorProps as k, buttonVariants as l, cardVariants as m };