Getting started, v0.35.0

Installation

Start with the visual Create studio, scaffold from the CLI, or add the kit to an existing app. Browse the component catalogue for live examples.

Choose how to start

Use the CLI

Scaffold a supported template, or configure an existing React app in the current folder.

Scaffold a new app

Scaffold Next.js (npm)

npx --yes -p @default-file/ui df-ui init -t next --name my-app

Configure the current project

Configure current project (npm)

npx --yes -p @default-file/ui df-ui init

Add a component

Add Button (npm)

npx --yes -p @default-file/ui df-ui add button

Add several at once

Add Button, Select, and Toast (npm)

npx --yes -p @default-file/ui df-ui add button select toast

Every name in the catalogue works as an argument. Dependencies resolve automatically, so adding a component also brings in the foundation and color system it needs.

Templates: next, vite, react-router, tanstack-start, astro, react. Laravel: create Inertia + React first, then run init.

Already have a React app? The same init command configures it in place. For steps written for your stack, choose your framework, or wire it yourself with the manual essentials.

Ownership and upgrades

Your customizations stay intact. Kit releases do not overwrite local component files unless you choose to upgrade them.

  • Copy source

    df-ui add writes files into your app. Edit them as product code. Running add again keeps existing files. Pass --force only when you choose to replace a local copy with the kit release. df-ui upgrade replaces every copied item recorded in df.json.

  • Package import

    Imports from @default-file/ui use the dependency. App source is not overwritten. You receive kit changes only when you upgrade that package.

  • Version

    Current release is v0.35.0. df-ui init records it in df.json. Check with df-ui version and df-ui info.

Replace a local file with the current release

Overwrite your Button with the kit version (npm)

npx --yes -p @default-file/ui df-ui add button --force

AI and MCP

Attach the kit over stdio MCP so any host that supports MCP can list components, read full prop tables, check coverage, and run init or add.

Start the MCP server

Start MCP stdio server (npm)

npx --yes -p @default-file/ui df-ui mcp

Discover without MCP

Coverage check (npm)

npx --yes -p @default-file/ui df-ui cover "settings form with select and toast" --json

Example host config

MCP host config

{
  "mcpServers": {
    "default-file-ui": {
      "command": "npx",
      "args": [
        "--yes",
        "-p",
        "@default-file/ui",
        "df-ui",
        "mcp"
      ]
    }
  }
}

Color system for scales, tokens, and utilities; full kit when you need components. Prefer get_component or df-ui show for every documented prop before inventing replacements. For bundled agent skills, see Agent skills.

Theme options

Set host theme on html and tokens once at init. Color scale, control density, radius, corner shape, and field hover border apply across kit chrome. Prefer the Create studio, or pass flags on the CLI.

Corner radius, shape, and hover border

Init with theme flags (npm)

npx --yes -p @default-file/ui df-ui init -t next --name my-app --radius 1rem --corner-shape smooth --hover-border on

Host attributes on html: data-df-color-scale (`detailed` or `compact`) for palette aliases, data-df-density (`cozy`, `comfortable`, or `compact`) for control heights, and data-df-hover-border (`on` or `off`) for field hover borders. Color scale compact is palette-only; control density compact is separate.

--radius <len> sets the base --radius token (xxs to 4xl derive from it). Default 0.625rem.

--corner-shape round|smooth sets --df-corner-shape. round is classic circular arcs (default). smooth is a continuous squircle. Override later on :root if needed.

--hover-border on|off sets --df-hover-border and expects data-df-hover-border on html. Default on. Input, Select, Search Input, and Color Picker follow this. Override one control with the hoverBorder prop.

Or configure visually in Create.

Manual :root override

Theme tokens

/* Host theme attributes (on html) */
<html
  data-df-color-scale="detailed"
  data-df-density="cozy"
  data-df-hover-border="on"
>
 
/* df-ui:radius */
:root {
  --radius: 1rem;
}
 
/* df-ui:corner-shape */
:root {
  --df-corner-shape: var(--df-corner-shape-smooth);
}
 
/* df-ui:hover-border */
:root {
  --df-hover-border: on;
}

Choose your framework

Each guide opens with the same three paths, then the steps for that stack.

Manual essentials

Prefer to wire it yourself? Install the package, import the stylesheet, and import components by path.

Package

Package install (npm)

npm install @default-file/ui react react-dom lucide-react

CSS

Full kit CSS

@import "@default-file/ui/css/df-index.css";

Color system only

@import "@default-file/ui/css/df-color-system.css";

Keep the import first in the file. Semantic tokens such as --background, --foreground, and --border are custom properties, so a later declaration of the same name under :root wins. Starter templates often ship those names. Remove or rename them so kit theming and dark mode stay intact.

Color System (copy source)

Color scales, semantic tokens, and utilities. Install without components.

Color system registry path

default-file/ui/color-system

Foundation (copy source)

Kit CSS entry, component styles, hooks, and cn. Depends on color-system. Install first for components.

Foundation registry path

default-file/ui/foundation

Each component page lists its registry path as default-file/ui/<name>. Component peers: React and React DOM; some items also need lucide-react (select, toast, search-input). Color system CSS does not require those peers.