DOCUMENTATION / INSTALLATION

    Make yourself at home.

    Add editable U.lib components directly to your React project. Initialize once, add the components you need, and make the source your own.

    01. Initialize your project

    This release supports matching React and React DOM versions 18.2+ within React 18, or React 19. Use an existing React or Next.js project with Node.js 18 or later and React declared in package.json. Run commands from the project root and choose your package manager.

    npx @scriptwithahmad/u-lib@0.2.2 init

    The CLI detects JavaScript or TypeScript, creates u-lib.json, copies the shared helper and compiled styles, and adds the stylesheet import to your application entry. It installs the required dependencies using your project's package manager. Tailwind configuration and the website's @/ alias are not required.

    02. Add editable components

    npx @scriptwithahmad/u-lib@0.2.2 add button input

    Source files are copied into your components directory with relative imports. Component dependencies, including other U.lib source files, are included automatically. Existing files are preserved; use --dry-run to preview changes or --overwrite to replace them.

    import { Button } from "./components/ui/button";
    import { Input } from "./components/ui/input";
    
    export default function App() {
      return <><Input label="Name" /><Button>Save</Button></>;
    }

    This example assumes the component is in your source directory. Adjust relative import paths to its location, or use your own configured alias.

    03. Install the complete members table

    npx @scriptwithahmad/u-lib@0.2.2 add members-table

    This block includes the website preview's search, role/status filters, action menus, and matching CSS module. Import its default export from ./components/members-table. The table command adds the primitive table components.

    CLI commands and options

    Use an existing React project with Node.js 18 or later and React declared in package.json. Run commands from its root. The CLI copies source; installing the compiled package separately is optional.

    npx @scriptwithahmad/u-lib@0.2.2 list

    List prints available CLI names, which can differ from catalog labels. Preview file writes and dependency changes before applying them:

    npx @scriptwithahmad/u-lib@0.2.2 add button input --dry-run
    OptionBehavior
    --dry-runPreview changes without writing files or installing dependencies.
    --skip-installCopy files and print dependencies for manual installation.
    --overwriteReplace existing generated source and CSS. Back up customizations first. The app entry only receives its stylesheet import update.
    --cwd <directory>Target an existing project from another directory.
    --js / --tsForce the source language on the first init.
    --entry <file>Select an existing app entry on the first init.
    --src-dir <path>Select the source directory on the first init.
    --help / --versionPrint CLI help or version.

    Configuration and generated files

    Initialization detects src when present, otherwise the project root. A tsconfig.json selects TypeScript; otherwise the CLI emits JavaScript. A typical TypeScript App Router project receives:

    {
      "version": 1,
      "tsx": true,
      "sourceDir": "src",
      "css": "src/styles/u-lib.css",
      "entry": "src/app/layout.tsx"
    }

    The CLI writes u-lib.json, src/lib/utils.ts and src/styles/u-lib.css, then imports the stylesheet in the existing entry before application overrides. Components go under src/components/ui. JavaScript output uses .js and .jsx extensions.

    Entry detection supports App Router layouts, Pages Router _app files and main/index files. Override detection on the first init:

    npx @scriptwithahmad/u-lib@0.2.2 init --js --src-dir src --entry src/main.jsx

    After initialization, edit u-lib.json directly. sourceDir controls the parent of components and lib; tsx selects the language; css selects the stylesheet; entry selects its importer. Output paths must stay inside the project and cannot pass through symlinks. Changing paths does not move old files; reconcile existing files and imports yourself.

    Next.js, Vite and import paths

    Keep your Next.js root layout as a server component. Generated interactive files retain client boundaries. Add the use client directive to your own files when using state, browser APIs or event handlers. From src/app/page.tsx use ../components/ui/button; from src/App.tsx use ./components/ui/button. Adjust website snippets to generated paths or your own alias.

    Vite typically imports styles through src/main.tsx or src/main.jsx. The members-table block needs CSS module support. Compiled CSS includes a base reset, theme tokens and component utilities. Modern Yarn supports yarn dlx; Yarn Classic users should run the npm/npx command.

    Alternative: npm package imports

    You can keep using the compiled npm package instead of copying source.

    npm install @scriptwithahmad/u-lib

    Import the package styles

    Import the compiled stylesheet once in your application entry point. In Next.js App Router, add it to your root layout. Tailwind CSS configuration is not required. The stylesheet includes Tailwind's base reset; import your application overrides after it.

    import "@scriptwithahmad/u-lib/styles.css";
    
    export default function RootLayout({ children }: { children: React.ReactNode }) {
      return <html lang="en"><body>{children}</body></html>;
    }

    Your own stylesheet is optional. Import it afterwards only if it exists, using its actual path. U.lib does not require a local globals.css file.

    Use a package component

    Import individual component entries to keep imports focused. Interactive examples belong in client components in Next.js.

    "use client";
    
    import { Button } from "@scriptwithahmad/u-lib/button";
    import { Card, CardHeader, CardTitle, CardContent } from "@scriptwithahmad/u-lib/card";
    
    export default function Example() {
      return (
        <Card>
          <CardHeader><CardTitle>Your next idea</CardTitle></CardHeader>
          <CardContent><Button animated>Save changes</Button></CardContent>
        </Card>
      );
    }

    You can also import named components from @scriptwithahmad/u-lib. Package imports work without the website's @/ alias. The catalog's source examples use that alias to show the website source; use the corresponding package entry, such as @scriptwithahmad/u-lib/dialog, in your own project.

    Styled defaults and Card composition

    Visual components include default styling through the shared stylesheet. Providers and behavioral roots are intentionally structural; their trigger/content parts render the interface. Website demos can add layout beyond the primitive.

    A bare Card includes a 24px inset. Compose CardHeader, CardContent and CardFooter as direct children to give each section its intended spacing without double padding. These defaults are included starting with version 0.2.1.

    import { Card, CardHeader, CardTitle, CardContent, CardFooter } from "./components/ui/card";
    import { Input } from "./components/ui/input";
    import { Button } from "./components/ui/button";
    
    export function ProfileCard() {
      return (
        <Card>
          <CardHeader><CardTitle>Your profile</CardTitle></CardHeader>
          <CardContent><Input label="Name" placeholder="Your name" /></CardContent>
          <CardFooter><Button>Save changes</Button></CardFooter>
        </Card>
      );
    }

    04. Themes and customization

    Apply className="dark" to your root HTML element for dark mode. Set data-accent to violet, blue, or sage. You can manage these attributes yourself or use next-themes. Controls accept native attributes and className; override theme variables in your stylesheet for broader changes.

    :root {
      --radius: 0.5rem;
      --control-accent: 229 100% 54%;
    }
    
    .dark {
      --control-accent: 225 100% 72%;
    }

    Global style variables

    Use global CSS variables for changes shared by every component. Use className for an individual component: its Tailwind defaults are merged with your classes through cn(). You can also edit the source installed by the CLI.

    Load overrides after the library styles

    With the CLI, keep the generated stylesheet import and create your own overrides file after it. With package imports, load the package stylesheet first. Choose one setup; you do not need both stylesheets.

    // CLI source installation
    import "./styles/u-lib.css";
    import "./styles/theme.css";
    
    // Or, with npm package imports
    import "@scriptwithahmad/u-lib/styles.css";
    import "./styles/theme.css";

    Adjust these paths to your application entry. In Next.js App Router, import global styles from your root layout. Keeping overrides in a separate file also makes it easier to review future CLI stylesheet updates.

    Set light and dark tokens

    Color tokens below store space-separated HSL channels, without an hsl() wrapper. For example, write --background: 0 0% 100%, then use hsl(var(--background)) in regular CSS. Keep foreground colors readable against their matching surfaces.

    /* styles/theme.css: import after U.lib styles */
    :root {
      --background: 0 0% 100%;
      --foreground: 222 47% 11%;
      --card: 0 0% 100%;
      --card-foreground: 222 47% 11%;
      --primary: 221 83% 53%;
      --primary-foreground: 0 0% 100%;
      --border: 214 32% 91%;
      --control-accent: 221 83% 53%;
      --radius: 0.75rem;
    }
    
    .dark {
      --background: 222 47% 8%;
      --foreground: 210 40% 98%;
      --card: 222 40% 12%;
      --card-foreground: 210 40% 98%;
      --primary: 217 91% 70%;
      --primary-foreground: 222 47% 11%;
      --border: 217 33% 24%;
      --control-accent: 217 91% 70%;
    }

    Activate the dark values with <html className="dark">, or let your theme provider manage that class. Variables inherit through the DOM, so a class such as .billing-theme can scope a palette to one section. Content rendered in a portal outside that section needs the same theme on its portal container or on the document root.

    Token reference

    VariablesPurpose
    --background / --foregroundPage background and default text.
    --card / --card-foregroundCard surface and its text.
    --popover / --popover-foregroundFloating menus, popovers and their text.
    --primary / --primary-foregroundPrimary utility colors; the default Button has separate gradient tokens below.
    --secondary / --secondary-foregroundSecondary surfaces and text.
    --muted / --muted-foregroundSubtle surfaces and supporting text.
    --accent / --accent-foregroundHighlighted or selected surfaces and text.
    --destructive / --destructive-foreground / --destructive-textDestructive surfaces, their foreground, and error text.
    --border / --input / --ringDefault borders, input borders and ring utilities.
    --control-accentSelection controls and custom field focus treatment; separate from --ring.
    --brand / --brand-foregroundBrand accents and contrasting brand text.
    --chart-1 through --chart-5Chart palette tokens; assign them in your chart configuration.
    --radiusBase radius for Tailwind rounded-lg/md/sm tokens. Explicit component radii remain independent.

    Customize accent presets

    The root data-accent="blue" and data-accent="sage" presets set several tokens together. To customize a preset, match its selector in your overrides file, including the dark selector. A plain :root rule has lower specificity than a preset selector.

    :root[data-accent="blue"] {
      --brand: 221 83% 53%;
      --brand-rgb: 37 99 235;
      --ring: 221 83% 53%;
      --accent: 214 100% 97%;
    }
    
    :root.dark[data-accent="blue"] {
      --brand: 217 91% 70%;
      --brand-rgb: 109 160 248;
      --ring: 217 91% 70%;
      --accent: 217 33% 20%;
    }

    --brand-rgb and --surface-rgb are exceptions: they store space-separated RGB channels, such as 37 99 235, for documentation surfaces and effects. They do not automatically update when you change the corresponding HSL token. Other color tokens in the reference use HSL channels.

    Component-specific defaults and local overrides

    The default primary Button uses --button-primary-fill, --button-primary-border and --button-primary-shadow. These take complete CSS values, including gradients and shadow lists. The fill and shadow variables control the resting appearance; hover and active defaults are separate Tailwind variants.

    :root {
      --button-primary-fill: linear-gradient(180deg, #2563eb, #1d4ed8);
      --button-primary-border: #1d4ed8;
      --button-primary-shadow: inset 0 1px 0 #ffffff24, 0 1px 2px #00000014;
    }
    <Card className="p-0 rounded-none border-0 shadow-none" />
    
    <Input
      label="Email"
      className="h-12"
      frameClassName="rounded-none bg-background"
    />
    
    <Button className="bg-none bg-blue-600 hover:bg-none hover:bg-blue-700 active:bg-none active:bg-blue-800">
      Save
    </Button>

    className styles the native input; frameClassName styles the decorated input surface; containerClassName styles its outer wrapper. Use matching variants for state overrides, such as data-[state=checked]:bg-blue-600. Custom Tailwind classes need your own Tailwind build, loaded after the library stylesheet. CSS variable overrides work without installing Tailwind.

    Some controls use explicit corners, gradients or state styles, so changing --radius or --primary does not restyle every detail. Use local utility overrides or edit copied source for those details. For optional motion, use the supported animated, duration and intensity props; preserve reduced-motion and high-contrast behavior.

    The included CSS supports reduced motion. Add motion-preferences with the CLI and mount MotionPreferences once if you also want repeated keyboard interactions to skip optional transitions.

    05. Notifications with Crisp Toast

    npx @scriptwithahmad/u-lib@0.2.2 add button
    npm install crisp-toast

    The bundled stylesheet includes Crisp Toast styling. Trigger notifications in a client event handler; no toaster provider is required. Pass your application's resolved appearance to darkMode.

    "use client";
    
    import { toast } from "crisp-toast";
    import { Button } from "./components/ui/button";
    
    export default function SaveButton() {
      return <Button onClick={() => toast({
        title: "Changes saved",
        color: "success",
        darkMode: document.documentElement.classList.contains("dark"),
        pauseOnHover: true,
      })}>Save changes</Button>;
    }

    Updates and troubleshooting

    Customize now, update later

    Use className and native props for local changes, theme variables for shared colors, and copied files for structural changes. Built-in utilities are precompiled; new Tailwind classes you add need your own Tailwind build or equivalent CSS. Preserve labels, keyboard behavior, refs and reduced-motion support when editing.

    Updating copied source

    Copied files belong to your app and do not update when an npm dependency changes. Commit customizations, preview add with the desired CLI version and --dry-run, then use --overwrite only after reviewing affected files. Review the resulting Git diff, including shared CSS and dependencies, and run application checks.

    Entry not found or initialization required

    Pass --entry with an existing file on the first init if detection fails. Run init and add in the same project, or pass --cwd. Once configuration exists, edit paths and language there rather than passing initialization options again.

    Unstyled components

    Check that your configured entry imports the copied CSS once, before application overrides. Avoid loading both copied CSS and package styles.css. Initialization replaces an existing package stylesheet import with the local import. Existing CSS is preserved unless --overwrite is supplied.

    Dependency installation fails

    The CLI keeps copied files and prints a retry command. After --skip-install, install the printed dependencies manually. It chooses the installer from package.json packageManager, then lockfiles, then npm. Docs tabs select only the command launcher. Missing or incompatible dependency ranges may be updated; non-semver ranges may require manual reconciliation. Your app keeps control of its React versions.

    Local package testing

    Maintainers can build and pack the library from this repository, then install the resulting tarball into another project before publishing.

    npm run build:library
    npm pack ./packages/ui
    
    # In your other project, use the actual tarball path:
    npm install /path/to/the-generated-package.tgz