Documentation

Composition

Build tasks from existing components with explicit state, labels, and client boundaries.

idle

Start with the documented anatomy

Search the component catalog before adding a wrapper. Use the page's executable examples and exported prop types. Keep required labels, descriptions, indicators, triggers, and popup parts together.

Components own appearance and interaction contracts. The application owns records, persistence, routing, authorization, and server failures. A completed UI callback does not mean that a server operation succeeded.

Component catalog

Compose the task layout

Use Stack for vertical rhythm, Inline for a row, and Grid for columns. Card, Frame, and Section express different content groupings. Use their documented APIs instead of arbitrary wrappers that duplicate spacing.

Keep primary actions close to the task they complete. Use neutral workareas for separate work zones and one field fill throughout.

Label and describe fields

Field groups the label, control, help, and error. Use a visible label. Placeholder text is an example or hint, not a replacement for the label.

Use invalid and FieldError for validation feedback. Keep read-only and disabled meanings separate. Bind TanStack Form fields through Field's field prop when the form engine owns their value and validation.

import { Field, FieldDescription, FieldLabel, Input } from "@mizen-labs/ui";

export function ContactEmail() {
  return (
    <Field name="contactEmail">
      <FieldLabel>Contact email</FieldLabel>
      <Input autoComplete="email" type="email" />
      <FieldDescription>Used for project updates.</FieldDescription>
    </Field>
  );
}

Keep one state owner

Use defaultValue or defaultChecked when the component owns an initial value. Use value or checked with the documented change callback when the app owns it. Do not switch between controlled and uncontrolled ownership during a component's lifetime.

Derive filtered records and counts from existing state. Put user actions in event handlers. Preserve loading, empty, error, and success states. Keep pending feedback associated with the action and prevent duplicate submission.

Server and Client boundaries

Next App Router pages and layouts are Server Components by default. Compose static content there. Put state, event handlers, browser APIs, and render callbacks in a file marked use client.

Create callbacks on the client side of the boundary. Functions cannot cross as ordinary serialized props. Some Mizen exports carry their own client directive; use a client wrapper when an interactive third-party export lacks one. ThemeScript belongs in the server document head.

"use client";

import { Button } from "@mizen-labs/ui/button";
import { useState } from "react";

export function ReviewAction() {
  const [reviewed, setReviewed] = useState(false);
  return (
    <Button disabled={reviewed} onClick={() => setReviewed(true)}>
      {reviewed ? "Reviewed" : "Mark reviewed"}
    </Button>
  );
}

Verify the whole task

Check keyboard order, focus return after overlays close, labels, and error associations. Exercise long content, narrow widths, both themes, and reduced motion. Keep numeric and date formatting deterministic during server rendering.

Do not style internal data-slot hooks or generated classes. Use supported props. For a custom app-owned host, use StyleX and semantic tokens. Build consumer CSS at a real integration checkpoint.