@conscia-labs/design-system 0.4.0 → 1.0.1

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. `1.0.0` is published as the stable v1 release.
+>
+> **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,16 @@ 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
+- LoadingButton
+- IconButton
 - Card
 - Checkbox
 - Collapsible
@@ -59,13 +80,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 +107,74 @@ 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 v1, install the explicit `1.0.0` range:
+
 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
@@ -233,6 +313,40 @@ export function CreateConnectionCard() {
 }
 ```
 
+### Text-in-track switches
+
+Use `LabeledSwitch` when the switch state should be visible inside the control.
+It keeps Base UI’s switch behavior and accepts any React node for either label:
+
+```tsx
+import { LabeledSwitch } from "@conscia-labs/design-system";
+
+<LabeledSwitch
+  aria-label="Deployment status"
+  defaultChecked
+  onLabel="ENABLED"
+  offLabel="DISABLED"
+/>
+```
+
+`Switch` also accepts `onLabel` and `offLabel` when a single API needs to support
+both the compact unlabeled style and the text-in-track style. If a label is
+provided without its pair, the missing label defaults to `ON` or `OFF`.
+
+### Loading buttons
+
+Use `LoadingButton` for async actions that need stable button layout while a
+mutation is pending. It disables the button, sets `aria-busy`, and replaces the
+normal content with a small spinner and `pendingLabel`:
+
+```tsx
+import { LoadingButton } from "@conscia-labs/design-system";
+
+<LoadingButton pending={saveMutation.isPending} pendingLabel="Saving…">
+  Save changes
+</LoadingButton>
+```
+
 ## Building an application shell
 
 The shared shell owns presentation and responsive behavior. The host application supplies routes, links, user context, and actions.
@@ -413,6 +527,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
@@ -432,14 +560,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
@@ -458,16 +584,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
@@ -576,7 +702,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 |
@@ -606,7 +732,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.
@@ -689,23 +815,46 @@ 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 a 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 a release. Replace `VERSION` with the package version you
+are releasing:
 
 ```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 VERSION --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 vVERSION"
+git tag -a vVERSION -m "Release vVERSION"
 git push origin main
-git push origin v0.2.1
+git push origin vVERSION
 ```
 
-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 the tag 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 };

package/dist/chunk-UVKRO5ER.js

@@ -0,0 +1,13 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+export {
+  __export,
+  __publicField
+};
+//# sourceMappingURL=chunk-UVKRO5ER.js.map

package/dist/chunk-UVKRO5ER.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}