diff --git a/apps/ui/content/docs/(root)/get-started.mdx b/apps/ui/content/docs/(root)/get-started.mdx index 7c497da2f..74cc0342b 100644 --- a/apps/ui/content/docs/(root)/get-started.mdx +++ b/apps/ui/content/docs/(root)/get-started.mdx @@ -25,7 +25,7 @@ For new projects, use the **coss style** preset to initialize everything in one npx shadcn@latest init @coss/style ``` -This installs all UI components, the neutral color system, sidebar variables, font variables, and base styles. Components like Dialog and AlertDialog use `font-heading` for titles—the style preset provides sensible fallbacks, and you can customize fonts via `next/font` in your layout. +This installs all UI components, the neutral color system, sidebar variables, and base styles. It also installs **Inter** (`--font-sans`, `--font-heading`) and **Geist Mono** (`--font-mono`) as default fonts, automatically configured in your `layout.tsx`. ### Existing Projects @@ -72,6 +72,31 @@ We've introduced a few additional tokens to provide more granular control: **Important**: If you manually import components, you must also import these additional tokens in your CSS file (e.g., `app/globals.css`). However, if you use the CLI to import components, these tokens will be automatically imported and configured for you. +## Fonts + +coss components use three CSS custom properties for typography: + +- `--font-sans` — Body text, buttons, labels, and most UI elements +- `--font-mono` — Code blocks, ``, monospace text +- `--font-heading` — Dialog and AlertDialog titles (defaults to Inter, same as `--font-sans`) + +When you use `@coss/style`, `@coss/fonts` is installed automatically — Inter for `--font-sans` and `--font-heading`, Geist Mono for `--font-mono` — all wired in your `layout.tsx`. + +### Custom fonts + +To use different fonts, ensure the `variable` option in your `next/font` configuration matches the expected CSS variables: + +```tsx +import { Inter } from "next/font/google"; +import { JetBrains_Mono } from "next/font/google"; + +const inter = Inter({ variable: "--font-sans", subsets: ["latin"] }); +const interHeading = Inter({ variable: "--font-heading", subsets: ["latin"] }); +const jetbrainsMono = JetBrains_Mono({ variable: "--font-mono", subsets: ["latin"] }); +``` + +**Note:** Next.js starters default to variable names like `--font-geist-sans`, which don't match coss's expected `--font-sans`. If fonts appear broken after setup, check that the variable names match. + ## Primitive exports Components that wrap Base UI primitives re-export the underlying primitive. Use the styled component when our defaults work, or the primitive when you need different compositions or styling. In a monorepo with a shared UI package, apps import from that package—Base UI stays in one place, no need to add it to each app. diff --git a/apps/ui/content/docs/(root)/radix-migration.mdx b/apps/ui/content/docs/(root)/radix-migration.mdx index df1f55d5c..f1979812b 100644 --- a/apps/ui/content/docs/(root)/radix-migration.mdx +++ b/apps/ui/content/docs/(root)/radix-migration.mdx @@ -1,7 +1,7 @@ --- title: Migrating from Radix slug: radix-migration -description: A comprehensive guide for migrating from Radix-based libraries to coss ui components. +description: A practical guide for migrating from Radix-based libraries to coss ui components. --- This guide is for developers who already have applications built on Radix-based libraries — frameworks that wrap Radix primitives — and **want to adopt coss ui**. @@ -22,7 +22,7 @@ This guide is for developers who already have applications built on Radix-based ### The asChild to render Pattern -The most common change across all components is replacing Radix UI's `asChild` prop with Base UI's `render` prop: +One of the most common migration changes is replacing Radix UI's `asChild` prop with Base UI's `render` prop (especially on trigger/close/composed parts): ```tsx title="Radix" @@ -33,6 +33,8 @@ The most common change across all components is replacing Radix UI's `asChild` p ``` +Not every component uses this pattern. Apply it where the coss component supports `render`. + ```tsx title="coss ui" // [!code word:render] @@ -608,15 +610,15 @@ Base UI introduces separate parts — `ProgressLabel`, `ProgressValue`, `Progres **Prop Mapping:** -| Component | Radix UI Prop | Base UI Prop | -| ------------- | ---------------------- | --------------- | -| `Select` | `items` | `items` | -| `SelectValue` | `placeholder` | _removed_ | -| `SelectPopup` | `alignItemWithTrigger` | _no equivalent_ | +| Component | Radix UI Prop | coss ui / Base UI Prop | +| ------------- | ---------------------------------------------- | ------------------------------------------- | +| `Select` | options inferred from `SelectItem` children | `items` prop (recommended for SSR/hydration) | +| `SelectValue` | `placeholder` | `placeholder` (supported on `SelectValue`) | +| `SelectPopup` | _no equivalent_ | `alignItemWithTrigger` | **Quick Checklist:** - Set `items` prop on `Select` -- Remove `placeholder` from `Select` +- Keep placeholder on `SelectValue` when needed - Prefer `SelectPopup` instead of `SelectContent` - If you used `asChild` on parts, switch to the `render` prop @@ -634,7 +636,9 @@ So, for example, if you were using the `default` size in shadcn/ui and you want **Additional Notes:** -Base UI introduces the `alignItemWithTrigger` prop to control whether the `SelectContent` overlaps the `SelectTrigger` so the selected item's text is aligned with the trigger's value text. +`alignItemWithTrigger` controls whether the popup aligns the selected item with the trigger text. In coss ui this prop is available on `SelectPopup` (legacy alias: `SelectContent`). + +`SelectValue` supports a `placeholder` prop. If you need in-popup clearing, prefer adding a `null` option item instead of relying on placeholder alone. **Comparison Example:** @@ -658,13 +662,15 @@ Base UI introduces the `alignItemWithTrigger` prop to control whether the `Selec ```tsx title="coss ui" // [!code word:alignItemWithTrigger={false}] // [!code word:items:2] +const items = [ + { label: "Select a framework", value: null }, + { label: "Next.js", value: "next" }, + { label: "Vite", value: "vite" }, + { label: "Astro", value: "astro" }, +] + ;\n}\n\nexport function InputGroupTextarea({\n className,\n ...props\n}: TextareaProps): React.ReactElement {\n return