boreal-ui 0.0.888 → 0.0.889

package/README.md

@@ -4,12 +4,14 @@ Boreal UI is a customizable, accessible React and Next.js component library with
 
 Use it when you want production-ready UI primitives that can be themed globally, customized per component, tested predictably, and imported in either standard React apps or Next.js app-router projects.
 
+[View the Boreal UI docs](https://www.borealui.ca)
+
 ## Highlights
 
 - **React and Next.js builds:** import from `boreal-ui/core` for React apps or `boreal-ui/next` for Next.js apps.
 - **Deep component set:** buttons, forms, navigation, data display, feedback, overlays, layout primitives, and utility components.
 - **Theme system:** curated color schemes, custom schemes, runtime theme selection, CSS variables, and `ThemeSelect`.
-- **Global defaults:** configure default theme, size, rounding, shadow, border width, glass, outline, and color scheme once with `borealConfig` or `setBorealStyleConfig`.
+- **Global defaults:** configure default theme, size, rounding, shadow, border width, glass, outline, and color scheme once with `borealConfig` or `setBorealStyleConfig`.
 - **Accessible by default:** semantic markup, ARIA support, keyboard behavior, visible focus states, disabled states, live announcements where useful, and predictable test IDs.
 - **Styling flexibility:** theme, state, size, rounding, shadow, outline, glass, custom class names, SCSS variables, and consumer CSS overrides.
 - **Typed public API:** TypeScript component props, shared type exports, and generated prop documentation objects for docs tooling.
@@ -17,30 +19,31 @@ Use it when you want production-ready UI primitives that can be themed globally,
 
 ## Installation
 
-```bash
-npm install boreal-ui
-```
-
-Boreal UI expects React and React DOM in the consuming app. Next.js users should also have Next installed. `marked` and `uuid` are peer dependencies because some components and utilities rely on them.
-
-## CLI Setup
-
-Use the CLI inside an existing React or Next.js project to add only the file changes Boreal UI needs: the package dependency, the global stylesheet import, `ThemeProvider`, and default style config.
-
-```bash
-npx boreal-ui@latest init
-```
-
-You can preview changes or run non-interactively:
-
-```bash
-npx boreal-ui init --dry-run
-npx boreal-ui init --framework next --yes
-```
-
-## Setup
-
-Import the global stylesheet once near the top of your application.
+```bash
+npm install boreal-ui
+```
+
+Boreal UI expects React and React DOM in the consuming app. Next.js users should also have Next installed. `marked` and `uuid` are peer dependencies because some components and utilities rely on them.
+
+## CLI Setup
+
+Use the CLI inside an existing React or Next.js project to add only the file changes Boreal UI needs: the package dependency, the global stylesheet import, `ThemeProvider`, and default style config.
+
+```bash
+npx boreal-ui@latest init
+```
+
+You can preview changes or run non-interactively:
+
+```bash
+npx boreal-ui init --dry-run
+npx boreal-ui init --framework next --yes
+npx boreal-ui init --framework next --recommended-globals
+```
+
+## Setup
+
+Import the global stylesheet once near the top of your application.
 
 ### React
 
@@ -73,7 +76,43 @@ Import the Next stylesheet once from `app/layout.tsx`, `pages/_app.tsx`, or your
 import "boreal-ui/next/globals.css";
 ```
 
-Then import components from the Next build:
+If your Next.js app still has the starter `globals.css` reset below, avoid loading it after Boreal styles:
+
+```css
+* {
+  box-sizing: border-box;
+  padding: 0;
+  margin: 0;
+}
+```
+
+The universal `padding` and `margin` reset can override spacing that Boreal components and nested content rely on. Prefer a narrower baseline:
+
+```css
+html {
+  box-sizing: border-box;
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: inherit;
+}
+
+body {
+  margin: 0;
+}
+```
+
+The CLI can create or repair that safer baseline for Next.js apps:
+
+```bash
+npx boreal-ui init --framework next --recommended-globals
+```
+
+Interactive Next.js setup prompts for this by default. Use `--recommended-globals` to apply it without the prompt, or `--no-recommended-globals` to skip it.
+
+Then import components from the Next build:
 
 ```tsx
 "use client";
@@ -101,7 +140,7 @@ import Card from "boreal-ui/next/Card";
 
 ## Components
 
-For deeper consumer API examples, see the [Boreal UI consumer API guides](./docs/README.md). They cover import paths, styling and theming, common component patterns, generated prop docs, public TypeScript types, and contributor workflow.
+For deeper consumer API examples, see the [Boreal UI consumer API guides](./docs/README.md). They cover import paths, styling and theming, common component patterns, generated prop docs, public TypeScript types, and contributor workflow.
 
 ### Actions
 
@@ -113,7 +152,7 @@ For deeper consumer API examples, see the [Boreal UI consumer API guides](./docs
 
 - `TextInput` and `TextArea` support labels, helper/error text, validation state, disabled state, sizing, theming, and accessible descriptions.
 - `Select` and `ThemeSelect` cover option selection and color-scheme switching.
-- `Checkbox`, `RadioButton`, `RadioGroup`, `Toggle`, and `Slider` provide common controlled input patterns.
+- `Checkbox`, `RadioButton`, `RadioGroup`, `Toggle`, and `Slider` provide common controlled input patterns.
 - `ColorPicker` supports color selection flows.
 - `DateTimePicker` handles date and time input.
 - `FileUpload` supports file selection UI.
@@ -161,28 +200,28 @@ Exact props vary by component. TypeScript and the generated prop docs are the so
 
 ## Global Style Defaults
 
-Call `borealConfig` once before rendering your app to set project-wide defaults. `setBorealStyleConfig` remains available as the explicit API name.
-
-```tsx
-import { borealConfig } from "boreal-ui/core";
-
-borealConfig({
-  defaultTheme: "secondary",
-  defaultSize: "medium",
-  defaultRounding: "medium",
-  defaultShadow: "light",
-  defaultBorderWidth: "none",
-  defaultGlass: false,
-  defaultOutline: false,
-  defaultColorSchemeName: "Forest Dusk",
-});
-```
-
-For Next.js, import the same API from `boreal-ui/next`:
-
-```tsx
-import { borealConfig } from "boreal-ui/next";
-```
+Call `borealConfig` once before rendering your app to set project-wide defaults. `setBorealStyleConfig` remains available as the explicit API name.
+
+```tsx
+import { borealConfig } from "boreal-ui/core";
+
+borealConfig({
+  defaultTheme: "secondary",
+  defaultSize: "medium",
+  defaultRounding: "medium",
+  defaultShadow: "light",
+  defaultBorderWidth: "none",
+  defaultGlass: false,
+  defaultOutline: false,
+  defaultColorSchemeName: "Forest Dusk",
+});
+```
+
+For Next.js, import the same API from `boreal-ui/next`:
+
+```tsx
+import { borealConfig } from "boreal-ui/next";
+```
 
 Component props still win over global defaults:
 
@@ -269,20 +308,20 @@ registerColorScheme({
 console.log(defaultColorSchemes.map((scheme) => scheme.name));
 ```
 
-## Generated Prop Docs
-
-Boreal UI exports generated prop metadata for documentation sites, playgrounds, or prop tables.
+## Generated Prop Docs
+
+Boreal UI exports generated prop metadata for documentation sites, playgrounds, or prop tables.
 
 ```tsx
 import { buttonPropDocs, dataTablePropDocs } from "boreal-ui/core";
 
 console.log(buttonPropDocs.name);
-console.log(dataTablePropDocs.props);
-```
-
-The docs export includes `GeneratedComponentDoc` and `GeneratedPropDoc` types, plus one prop-doc object per documented component. Prop docs include `defaultValue` when the component implementation sets a readable default.
-
-For the complete generated prop-doc export list, see [Public API Reference](./docs/public-api-reference.md).
+console.log(dataTablePropDocs.props);
+```
+
+The docs export includes `GeneratedComponentDoc` and `GeneratedPropDoc` types, plus one prop-doc object per documented component. Prop docs include `defaultValue` when the component implementation sets a readable default.
+
+For the complete generated prop-doc export list, see [Public API Reference](./docs/public-api-reference.md).
 
 ## Type Exports
 
@@ -372,9 +411,9 @@ Useful scripts:
 | `npm run audit`                | Run type, lint, style, test, build, and package checks. |
 | `npm run generate:docs`        | Regenerate component prop docs.                         |
 | `npm run generate:entrypoints` | Regenerate component entry points.                      |
-| `npm run generate:exports`     | Regenerate package exports.                             |
-
-Contributor documentation for component structure, generated docs, package output, and release checks lives in [Development Workflow](./docs/development-workflow.md).
+| `npm run generate:exports`     | Regenerate package exports.                             |
+
+Contributor documentation for component structure, generated docs, package output, and release checks lives in [Development Workflow](./docs/development-workflow.md).
 
 ## Package Entry Points
 

package/README.npm.md

@@ -0,0 +1,448 @@
+# Boreal UI
+
+Boreal UI is a customizable, accessible React and Next.js component library with SCSS-powered theming, TypeScript types, generated prop metadata, and parallel `core` and `next` package outputs.
+
+Use it when you want production-ready UI primitives that can be themed globally, customized per component, tested predictably, and imported in either standard React apps or Next.js app-router projects.
+
+## Highlights
+
+- **React and Next.js builds:** import from `boreal-ui/core` for React apps or `boreal-ui/next` for Next.js apps.
+- **Deep component set:** buttons, forms, navigation, data display, feedback, overlays, layout primitives, and utility components.
+- **Theme system:** curated color schemes, custom schemes, runtime theme selection, CSS variables, and `ThemeSelect`.
+- **Global defaults:** configure default theme, size, rounding, shadow, border width, glass, outline, and color scheme once with `borealConfig`.
+- **Accessible by default:** semantic markup, ARIA support, keyboard behavior, visible focus states, disabled states, live announcements where useful, and predictable test IDs.
+- **Styling flexibility:** theme, state, size, rounding, shadow, outline, glass, custom class names, SCSS variables, and consumer CSS overrides.
+- **Typed public API:** TypeScript component props, shared type exports, and generated prop documentation objects for docs tooling.
+
+## Installation
+
+```bash
+npm install boreal-ui
+```
+
+Boreal UI expects React and React DOM in the consuming app. Next.js users should also have Next installed.
+
+Some components and utilities rely on `marked` and `uuid`, so make sure they are available if your package manager does not install peer dependencies automatically.
+
+## CLI Setup
+
+Use the CLI inside an existing React or Next.js project to add the package dependency, global stylesheet import, `ThemeProvider`, and default style config.
+
+```bash
+npx boreal-ui@latest init
+```
+
+Preview changes before writing files:
+
+```bash
+npx boreal-ui init --dry-run
+```
+
+Run non-interactively:
+
+```bash
+npx boreal-ui init --framework next --yes
+```
+
+For Next.js projects, you can also apply Boreal’s recommended global CSS baseline:
+
+```bash
+npx boreal-ui init --framework next --recommended-globals
+```
+
+## Setup
+
+Import the global stylesheet once near the top of your application.
+
+## React
+
+```tsx
+import "boreal-ui/core/globals.css";
+```
+
+Then import components from the core build:
+
+```tsx
+import { Button, Card, TextInput } from "boreal-ui/core";
+
+export function Example() {
+  return (
+    <Card title="Welcome" theme="primary" shadow="medium">
+      <TextInput label="Project name" placeholder="Aurora dashboard" />
+      <Button theme="secondary" size="large">
+        Continue
+      </Button>
+    </Card>
+  );
+}
+```
+
+## Next.js
+
+Import the Next stylesheet once from `app/layout.tsx`, `pages/_app.tsx`, or your global stylesheet.
+
+```tsx
+import "boreal-ui/next/globals.css";
+```
+
+Then import components from the Next build:
+
+```tsx
+"use client";
+
+import { Button, Card, TextInput } from "boreal-ui/next";
+
+export default function Example() {
+  return (
+    <Card title="Welcome" theme="primary" shadow="medium">
+      <TextInput label="Project name" placeholder="Aurora dashboard" />
+      <Button theme="secondary" size="large">
+        Continue
+      </Button>
+    </Card>
+  );
+}
+```
+
+### Next.js Global CSS Note
+
+If your Next.js app still has the default starter reset below, avoid loading it after Boreal styles:
+
+```css
+* {
+  box-sizing: border-box;
+  padding: 0;
+  margin: 0;
+}
+```
+
+The universal `padding` and `margin` reset can override spacing that Boreal components and nested content rely on.
+
+Prefer this safer baseline:
+
+```css
+html {
+  box-sizing: border-box;
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: inherit;
+}
+
+body {
+  margin: 0;
+}
+```
+
+## Standalone Component Imports
+
+You can import individual components directly:
+
+```tsx
+import Button from "boreal-ui/core/Button";
+import Card from "boreal-ui/next/Card";
+```
+
+## Package Entry Points
+
+```tsx
+import { Button } from "boreal-ui/core";
+import Button from "boreal-ui/core/Button";
+import "boreal-ui/core/globals.css";
+
+import { Button as NextButton } from "boreal-ui/next";
+import NextCard from "boreal-ui/next/Card";
+import "boreal-ui/next/globals.css";
+```
+
+The root `boreal-ui` entry currently points to the core build. For Next.js apps, prefer `boreal-ui/next` so the Next wrappers and client directives are used.
+
+## Components
+
+### Actions
+
+- `Button`
+- `IconButton`
+- `ScrollToTop`
+
+### Forms and Inputs
+
+- `TextInput`
+- `TextArea`
+- `Select`
+- `ThemeSelect`
+- `Checkbox`
+- `RadioButton`
+- `RadioGroup`
+- `Toggle`
+- `Slider`
+- `ColorPicker`
+- `DateTimePicker`
+- `FileUpload`
+- `TagInput`
+- `FormGroup`
+
+### Data and Content
+
+- `DataTable`
+- `MarkdownRenderer`
+- `Typography`
+- `MetricBox`
+
+### Feedback and Status
+
+- `Badge`
+- `Chip`
+- `ChipGroup`
+- `Progressbar`
+- `CircularProgress`
+- `Spinner`
+- `Skeleton`
+- `Rating`
+- `Tooltip`
+- `MessagePopup`
+- `PopOver`
+- `Modal`
+- `NotificationCenter`
+- `EmptyState`
+
+### Navigation and Layout
+
+- `Navbar`
+- `Sidebar`
+- `Footer`
+- `Breadcrumbs`
+- `Tabs`
+- `Stepper`
+- `Timeline`
+- `Accordion`
+- `Pager`
+- `Toolbar`
+- `Dropdown`
+- `Divider`
+- `Card`
+- `Avatar`
+
+## Common Styling Props
+
+Many components share the same styling vocabulary:
+
+| Prop          | Values                                                    |
+| ------------- | --------------------------------------------------------- |
+| `theme`       | `primary`, `secondary`, `tertiary`, `quaternary`, `clear` |
+| `state`       | `success`, `error`, `warning`, `disabled`, empty string   |
+| `size`        | `xs`, `small`, `medium`, `large`, `xl`                    |
+| `rounding`    | `none`, `small`, `medium`, `large`, `full`                |
+| `shadow`      | `none`, `light`, `medium`, `strong`, `intense`            |
+| `borderWidth` | `none`, `xs`, `small`, `medium`, `large`, `xl`            |
+| `outline`     | outline treatment where supported                         |
+| `glass`       | translucent theme-aware surface where supported           |
+| `className`   | consumer styling hook                                     |
+| `data-testid` | stable test selector                                      |
+
+Exact props vary by component. TypeScript and the generated prop docs are the source of truth for each component.
+
+## Global Style Defaults
+
+Call `borealConfig` once before rendering your app to set project-wide defaults.
+
+```tsx
+import { borealConfig } from "boreal-ui/core";
+
+borealConfig({
+  defaultTheme: "secondary",
+  defaultSize: "medium",
+  defaultRounding: "medium",
+  defaultShadow: "light",
+  defaultBorderWidth: "none",
+  defaultGlass: false,
+  defaultOutline: false,
+  defaultColorSchemeName: "Forest Dusk",
+});
+```
+
+For Next.js, import the same API from `boreal-ui/next`:
+
+```tsx
+import { borealConfig } from "boreal-ui/next";
+```
+
+Component props still win over global defaults:
+
+```tsx
+<Button theme="primary" size="large" shadow="strong">
+  Save changes
+</Button>
+```
+
+## Theme Provider and Color Schemes
+
+`ThemeProvider` manages the active color scheme and writes the scheme into CSS variables used by Boreal UI components.
+
+```tsx
+"use client";
+
+import { ThemeProvider } from "boreal-ui/next";
+
+const customSchemes = [
+  {
+    name: "Cyberpunk Pulse",
+    primaryColor: "#ff006e",
+    secondaryColor: "#8338ec",
+    tertiaryColor: "#3a0ca3",
+    quaternaryColor: "#fb5607",
+    backgroundColor: "#0f0f0f",
+    forceTextColor: "#ffffff",
+  },
+];
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <ThemeProvider
+      customSchemes={customSchemes}
+      initialSchemeName="Cyberpunk Pulse"
+    >
+      {children}
+    </ThemeProvider>
+  );
+}
+```
+
+### ThemeProvider Props
+
+| Prop                   | Description                                           |
+| ---------------------- | ----------------------------------------------------- |
+| `customSchemes`        | Register additional color schemes at runtime.         |
+| `initialSchemeName`    | Select an initial scheme by name.                     |
+| `useOnlyCustomSchemes` | Use only custom schemes instead of the built-in list. |
+
+### Color Scheme Shape
+
+```ts
+type ColorScheme = {
+  name: string;
+  primaryColor: string;
+  secondaryColor: string;
+  tertiaryColor: string;
+  quaternaryColor: string;
+  backgroundColor: string;
+  forceTextColor?: string;
+};
+```
+
+You can also register schemes manually:
+
+```tsx
+import {
+  defaultColorSchemes,
+  registerColorScheme,
+  ThemeSelect,
+} from "boreal-ui/core";
+
+registerColorScheme({
+  name: "Brand Night",
+  primaryColor: "#4f46e5",
+  secondaryColor: "#06b6d4",
+  tertiaryColor: "#a855f7",
+  quaternaryColor: "#22c55e",
+  backgroundColor: "#0f172a",
+  forceTextColor: "#ffffff",
+});
+
+console.log(defaultColorSchemes.map((scheme) => scheme.name));
+```
+
+## Type Exports
+
+Shared public types are exported from both builds:
+
+```ts
+import type {
+  BorderType,
+  ColorScheme,
+  RoundingType,
+  ShadowType,
+  SizeType,
+  ThemeType,
+} from "boreal-ui/core";
+```
+
+Standalone type entry points are also available:
+
+```ts
+import type { ThemeType } from "boreal-ui/core/types";
+import type { SizeType } from "boreal-ui/next/types";
+```
+
+## Generated Prop Docs
+
+Boreal UI exports generated prop metadata for documentation sites, playgrounds, and prop tables.
+
+```tsx
+import { buttonPropDocs, dataTablePropDocs } from "boreal-ui/core";
+
+console.log(buttonPropDocs.name);
+console.log(dataTablePropDocs.props);
+```
+
+The docs export includes `GeneratedComponentDoc` and `GeneratedPropDoc` types, plus one prop-doc object per documented component.
+
+## CSS Customization
+
+Boreal UI styles are built on CSS variables and SCSS. You can override variables globally or scope them to a subtree:
+
+```css
+:root {
+  --font-family-ui: Inter, system-ui, sans-serif;
+  --border-radius-md: 0.5rem;
+  --transition-default: 160ms ease;
+  --focus-outline-color: #2563eb;
+}
+
+.admin-shell {
+  --background-color: #0f172a;
+  --text-color: #f8fafc;
+}
+```
+
+Most components also accept `className`, and larger components expose section-level class props such as:
+
+```tsx
+<Card
+  title="Custom Card"
+  className="dashboard-card"
+  headerClassName="dashboard-card__header"
+  contentClassName="dashboard-card__content"
+  footerClassName="dashboard-card__footer"
+/>
+```
+
+## Accessibility and Testing
+
+Boreal UI is designed for Testing Library, Jest, jest-axe, Cypress, and Storybook workflows.
+
+- Prefer roles and accessible names in tests.
+- Use `data-testid` when a stable selector is needed.
+- Icon-only controls should receive an accessible label.
+- Helper and error text are connected with ARIA where components support those states.
+- Interactive components are built with keyboard behavior and visible focus states in mind.
+
+```tsx
+import { render, screen } from "@testing-library/react";
+import { Button } from "boreal-ui/core";
+
+it("renders an accessible button", () => {
+  render(<Button>Submit</Button>);
+  expect(screen.getByRole("button", { name: /submit/i })).toBeInTheDocument();
+});
+```
+
+## Documentation
+
+For full documentation, examples, and API guides, [View the Boreal UI docs](https://www.borealui.ca)
+
+## License
+
+MIT © Davin Chiupka

package/docs/installation-and-imports.md

@@ -46,16 +46,54 @@ export function ProjectForm() {
 
 ## Next.js Setup
 
-Import the Next stylesheet once from `app/layout.tsx`, `pages/_app.tsx`, or another global stylesheet loaded by the app.
-
-```tsx
-import "boreal-ui/next/globals.css";
-```
-
-Use the Next build for components.
-
-```tsx
-"use client";
+Import the Next stylesheet once from `app/layout.tsx`, `pages/_app.tsx`, or another global stylesheet loaded by the app.
+
+```tsx
+import "boreal-ui/next/globals.css";
+```
+
+Next.js starter projects often include this broad reset in the app's default `globals.css`:
+
+```css
+* {
+  box-sizing: border-box;
+  padding: 0;
+  margin: 0;
+}
+```
+
+Avoid loading that reset after Boreal styles. The universal `padding` and `margin` rules can override spacing that Boreal components and nested content rely on. Prefer a narrower global override that keeps box sizing predictable without removing spacing from every element:
+
+```css
+html {
+  box-sizing: border-box;
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: inherit;
+}
+
+body {
+  margin: 0;
+}
+```
+
+If your app needs additional layout resets, scope them to your own shell classes instead of applying them to every element globally.
+
+The CLI can create or repair that safer baseline for Next.js apps:
+
+```bash
+npx boreal-ui init --framework next --recommended-globals
+```
+
+Interactive Next.js setup prompts for this by default. Use `--recommended-globals` to apply it without the prompt, or `--no-recommended-globals` to skip it.
+
+Use the Next build for components.
+
+```tsx
+"use client";
 
 import { Button, Card, TextInput } from "boreal-ui/next";
 

package/docs/styling-and-theming.md

@@ -10,15 +10,53 @@ Import the global stylesheet once.
 import "boreal-ui/core/globals.css";
 ```
 
-For Next.js:
-
-```tsx
-import "boreal-ui/next/globals.css";
-```
-
-The global stylesheet provides CSS variables, resets, theme values, animations, and shared utility styles used by components.
-
-## Shared Style Props
+For Next.js:
+
+```tsx
+import "boreal-ui/next/globals.css";
+```
+
+The global stylesheet provides CSS variables, resets, theme values, animations, and shared utility styles used by components.
+
+Be careful with the default `globals.css` created by many Next.js starters:
+
+```css
+* {
+  box-sizing: border-box;
+  padding: 0;
+  margin: 0;
+}
+```
+
+When that reset is loaded after Boreal, the universal `padding` and `margin` declarations can override spacing used by Boreal components and nested content. A safer app-level baseline is:
+
+```css
+html {
+  box-sizing: border-box;
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: inherit;
+}
+
+body {
+  margin: 0;
+}
+```
+
+Keep broader spacing rules scoped to your app shell, page layouts, or utility classes so they do not erase component-level padding and margins.
+
+The CLI can create or repair that safer baseline for Next.js apps:
+
+```bash
+npx boreal-ui init --framework next --recommended-globals
+```
+
+Interactive Next.js setup prompts for this by default. Use `--recommended-globals` to apply it without the prompt, or `--no-recommended-globals` to skip it.
+
+## Shared Style Props
 
 Many components support a common styling vocabulary.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "boreal-ui",
-  "version": "0.0.888",
+  "version": "0.0.889",
   "description": "A modern, customizable React/Next.js component library",
   "author": "Davin Chiupka",
   "license": "MIT",

package/packages/cli/src/commands/init.js

@@ -1,6 +1,7 @@
 /* eslint-disable no-undef */
 import {
   existsSync,
+  mkdirSync,
   readFileSync,
   statSync,
   writeFileSync,
@@ -23,6 +24,20 @@ const BOREAL_CONFIG_CALL = `setBorealStyleConfig({
   defaultColorSchemeName: "Forest Dusk",
 });
 `;
+const NEXT_RECOMMENDED_GLOBALS = `html {
+  box-sizing: border-box;
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: inherit;
+}
+
+body {
+  margin: 0;
+}
+`;
 
 export async function initCommand(rawOptions) {
   const options = await promptForOptions(rawOptions);
@@ -41,7 +56,8 @@ export async function initCommand(rawOptions) {
   const packageJson = readPackageJson(packageJsonPath);
   const framework = resolveFramework(root, packageJson, options.framework);
   const packageManager = resolvePackageManager(root, options.packageManager);
-  const plan = createSetupPlan(root, packageJsonPath, packageJson, framework);
+  options.recommendedGlobals = await resolveRecommendedGlobalsOption(options, framework);
+  const plan = createSetupPlan(root, packageJsonPath, packageJson, framework, options);
 
   if (plan.length === 0) {
     console.log("Boreal UI already looks configured for this project.");
@@ -60,6 +76,7 @@ export async function initCommand(rawOptions) {
   try {
     for (const change of plan) {
       if (await shouldApplyChange(rl, change, options.yes)) {
+        mkdirSync(dirname(change.path), { recursive: true });
         writeFileSync(change.path, change.nextContents, "utf8");
         appliedCount += 1;
         console.log(`Updated ${relative(root, change.path) || basename(change.path)}`);
@@ -114,13 +131,32 @@ function resolvePackageManager(root, requestedPackageManager) {
   return "npm";
 }
 
-function createSetupPlan(root, packageJsonPath, packageJson, framework) {
+async function resolveRecommendedGlobalsOption(options, framework) {
+  if (framework !== "next") return false;
+  if (typeof options.recommendedGlobals === "boolean") return options.recommendedGlobals;
+  if (options.yes) return true;
+  if (options.dryRun) return false;
+
+  const rl = createInterface({ input, output });
+
+  try {
+    return await promptBoolean(
+      rl,
+      "Create or repair a Boreal-safe Next globals.css baseline?",
+      true,
+    );
+  } finally {
+    rl.close();
+  }
+}
+
+function createSetupPlan(root, packageJsonPath, packageJson, framework, options) {
   const changes = [];
 
   addPackageJsonChange(changes, packageJsonPath, packageJson);
 
   if (framework === "next") {
-    addNextChanges(changes, root);
+    addNextChanges(changes, root, options);
     return changes;
   }
 
@@ -179,11 +215,19 @@ function addReactChanges(changes, root) {
   }
 }
 
-function addNextChanges(changes, root) {
+function addNextChanges(changes, root, options) {
   const pagesAppPath = findFirst(root, nextPagesAppCandidates());
 
   if (pagesAppPath) {
-    addNextPagesRouterChange(changes, pagesAppPath);
+    const globalsPath = resolveNextGlobalsPath(root, pagesAppPath, "pages", options);
+
+    addNextPagesRouterChange(changes, pagesAppPath, globalsPath);
+    addNextRecommendedGlobalsChange(changes, root, {
+      enabled: options.recommendedGlobals,
+      globalsPath,
+      routerEntryPath: pagesAppPath,
+      routerType: "pages",
+    });
     return;
   }
 
@@ -197,16 +241,30 @@ function addNextChanges(changes, root) {
   const resolvedProviderPath =
     providerPath ?? join(dirname(layoutPath), `boreal-provider.${extensionFor(layoutPath)}`);
   const providerImportPath = `./${basename(resolvedProviderPath).replace(/\.[^.]+$/, "")}`;
+  const globalsPath = resolveNextGlobalsPath(root, layoutPath, "app", options);
 
   addNextProviderChange(changes, resolvedProviderPath);
-  addNextLayoutChange(changes, layoutPath, providerImportPath);
+  addNextLayoutChange(changes, layoutPath, providerImportPath, globalsPath);
+  addNextRecommendedGlobalsChange(changes, root, {
+    enabled: options.recommendedGlobals,
+    globalsPath,
+    routerEntryPath: layoutPath,
+    routerType: "app",
+  });
 }
 
-function addNextPagesRouterChange(changes, pagesAppPath) {
+function addNextPagesRouterChange(changes, pagesAppPath, globalsPath) {
   const source = readFileSync(pagesAppPath, "utf8");
   let nextSource = source;
 
   nextSource = ensureSideEffectImport(nextSource, "boreal-ui/next/globals.css");
+  if (globalsPath) {
+    nextSource = ensureSideEffectImportAfter(
+      nextSource,
+      toImportSpecifier(pagesAppPath, globalsPath),
+      "boreal-ui/next/globals.css",
+    );
+  }
   nextSource = ensureNamedImport(nextSource, "boreal-ui/next", [
     "ThemeProvider",
     "setBorealStyleConfig",
@@ -224,13 +282,20 @@ function addNextPagesRouterChange(changes, pagesAppPath) {
   }
 }
 
-function addNextLayoutChange(changes, layoutPath, providerImportPath) {
+function addNextLayoutChange(changes, layoutPath, providerImportPath, globalsPath) {
   const source = readFileSync(layoutPath, "utf8");
   let nextSource = source;
   const providerImportName =
     getDefaultImportName(source, providerImportPath) ?? "BorealProvider";
 
   nextSource = ensureSideEffectImport(nextSource, "boreal-ui/next/globals.css");
+  if (globalsPath) {
+    nextSource = ensureSideEffectImportAfter(
+      nextSource,
+      toImportSpecifier(layoutPath, globalsPath),
+      "boreal-ui/next/globals.css",
+    );
+  }
   nextSource = ensureDefaultImport(nextSource, providerImportName, providerImportPath);
   nextSource = ensureNextLayoutProvider(nextSource, providerImportName);
 
@@ -272,6 +337,49 @@ function addNextProviderChange(changes, providerPath) {
   }
 }
 
+function addNextRecommendedGlobalsChange(
+  changes,
+  root,
+  { enabled, globalsPath, routerEntryPath, routerType },
+) {
+  if (!enabled) return;
+
+  const resolvedGlobalsPath =
+    globalsPath ?? defaultNextGlobalsPath(root, routerEntryPath, routerType);
+  const exists = existsSync(resolvedGlobalsPath);
+  const source = exists ? readFileSync(resolvedGlobalsPath, "utf8") : "";
+  const nextSource = ensureRecommendedNextGlobals(source);
+
+  if (nextSource !== source) {
+    changes.push({
+      path: resolvedGlobalsPath,
+      summary: exists
+        ? "Replace broad Next.js global spacing resets with a Boreal-safe globals.css baseline."
+        : "Create a Boreal-safe Next.js globals.css baseline.",
+      nextContents: nextSource,
+    });
+  }
+}
+
+function resolveNextGlobalsPath(root, routerEntryPath, routerType, options) {
+  if (!options.recommendedGlobals) return undefined;
+
+  return (
+    findFirst(root, nextGlobalsCandidates()) ??
+    defaultNextGlobalsPath(root, routerEntryPath, routerType)
+  );
+}
+
+function toImportSpecifier(fromPath, targetPath) {
+  let specifier = relative(dirname(fromPath), targetPath).replace(/\\/g, "/");
+
+  if (!specifier.startsWith(".")) {
+    specifier = `./${specifier}`;
+  }
+
+  return specifier;
+}
+
 function ensureSideEffectImport(source, specifier) {
   if (source.includes(`"${specifier}"`) || source.includes(`'${specifier}'`)) {
     return source;
@@ -280,6 +388,22 @@ function ensureSideEffectImport(source, specifier) {
   return insertAfterUseClient(source, `import "${specifier}";\n`);
 }
 
+function ensureSideEffectImportAfter(source, specifier, afterSpecifier) {
+  if (source.includes(`"${specifier}"`) || source.includes(`'${specifier}'`)) {
+    return source;
+  }
+
+  const afterImportRegex = new RegExp(
+    `(import\\s*["']${escapeRegExp(afterSpecifier)}["'];?\\s*)`,
+  );
+
+  if (afterImportRegex.test(source)) {
+    return source.replace(afterImportRegex, `$1import "${specifier}";\n`);
+  }
+
+  return ensureSideEffectImport(source, specifier);
+}
+
 function ensureNamedImport(source, specifier, names) {
   const importRegex = new RegExp(
     `import\\s*\\{([^}]+)\\}\\s*from\\s*["']${escapeRegExp(specifier)}["'];?`,
@@ -420,6 +544,29 @@ function ensureUseClient(source) {
   return `"use client";\n\n${source}`;
 }
 
+function ensureRecommendedNextGlobals(source) {
+  if (!source.trim()) return NEXT_RECOMMENDED_GLOBALS;
+
+  const starterResetRegex = /\*\s*\{(?=[^}]*box-sizing\s*:\s*border-box\s*;?)(?=[^}]*padding\s*:\s*0\s*;?)(?=[^}]*margin\s*:\s*0\s*;?)[^}]*\}/m;
+  const hasRecommendedBoxSizing =
+    /html\s*\{[^}]*box-sizing\s*:\s*border-box\s*;?[^}]*\}/m.test(source) &&
+    /\*\s*,\s*\*::before\s*,\s*\*::after\s*\{[^}]*box-sizing\s*:\s*inherit\s*;?[^}]*\}/m.test(source);
+
+  let nextSource = source;
+
+  if (starterResetRegex.test(nextSource)) {
+    nextSource = nextSource.replace(starterResetRegex, NEXT_RECOMMENDED_GLOBALS.trimEnd());
+  } else if (!hasRecommendedBoxSizing) {
+    nextSource = `${NEXT_RECOMMENDED_GLOBALS}\n${nextSource}`;
+  }
+
+  if (!/body\s*\{[^}]*margin\s*:\s*0\s*;?[^}]*\}/m.test(nextSource)) {
+    nextSource = `${nextSource.trimEnd()}\n\nbody {\n  margin: 0;\n}\n`;
+  }
+
+  return nextSource.endsWith("\n") ? nextSource : `${nextSource}\n`;
+}
+
 function insertAfterUseClient(source, text) {
   const useClientRegex = /^(\s*["']use client["'];?\s*)/;
   const match = source.match(useClientRegex);
@@ -501,6 +648,26 @@ function nextPagesAppCandidates() {
   ]);
 }
 
+function nextGlobalsCandidates() {
+  return [
+    "app/globals.css",
+    "src/app/globals.css",
+    "styles/globals.css",
+    "src/styles/globals.css",
+  ];
+}
+
+function defaultNextGlobalsPath(root, routerEntryPath, routerType) {
+  if (routerType === "app") {
+    return join(dirname(routerEntryPath), "globals.css");
+  }
+
+  const pagesDirectory = dirname(routerEntryPath);
+  const sourceDirectory = basename(pagesDirectory) === "pages" ? dirname(pagesDirectory) : root;
+
+  return join(sourceDirectory, "styles", "globals.css");
+}
+
 function nextProviderCandidates(layoutDirectory) {
   return SOURCE_EXTENSIONS.flatMap((extension) => [
     join(layoutDirectory, `providers.${extension}`),
@@ -535,6 +702,17 @@ async function shouldApplyChange(rl, change, yes) {
   return !answer || ["y", "yes", "true", "1"].includes(answer);
 }
 
+async function promptBoolean(rl, question, defaultValue) {
+  const suffix = defaultValue ? "Y/n" : "y/N";
+  const answer = (await rl.question(`${question} (${suffix}): `))
+    .trim()
+    .toLowerCase();
+
+  if (!answer) return defaultValue;
+
+  return ["y", "yes", "true", "1"].includes(answer);
+}
+
 function printPlan(root, framework, plan, dryRun) {
   console.log(`Boreal UI setup for ${framework === "next" ? "Next.js" : "React"} at ${root}`);
   console.log(dryRun ? "Planned changes:" : "Proposed changes:");

package/packages/cli/src/utils/args.js

@@ -8,6 +8,7 @@ export async function parseArgs(argv) {
     framework: undefined,
     install: undefined,
     packageManager: undefined,
+    recommendedGlobals: undefined,
     dryRun: false,
     yes: false,
   };
@@ -66,10 +67,18 @@ export async function parseArgs(argv) {
       case "--package-manager":
         options.packageManager = rest.shift();
         break;
-
-      default:
-        if (arg?.startsWith("--")) {
-          fail(`Unknown option: ${arg}`);
+
+      case "--recommended-globals":
+        options.recommendedGlobals = true;
+        break;
+
+      case "--no-recommended-globals":
+        options.recommendedGlobals = false;
+        break;
+
+      default:
+        if (arg?.startsWith("--")) {
+          fail(`Unknown option: ${arg}`);
         }
 
         if (!options.cwd) {

package/packages/cli/src/utils/constants.js

@@ -1,7 +1,7 @@
-export const VERSION = "0.0.888";
-
-export const FRAMEWORKS = new Set(["react", "next"]);
-
+export const VERSION = "0.0.889";
+
+export const FRAMEWORKS = new Set(["react", "next"]);
+
 export const PACKAGE_MANAGERS = new Set(["npm", "pnpm", "yarn"]);
 
 export const DEFAULT_OPTIONS = {

package/packages/cli/src/utils/help.js

@@ -15,6 +15,8 @@ Options:
   --dry-run, --check              Show planned edits without writing files
   --install                       Run dependency install after edits
   --package-manager <name>        npm, pnpm, or yarn
+  --recommended-globals           Add a Boreal-safe Next globals.css baseline without prompting
+  --no-recommended-globals        Skip the recommended Next globals.css prompt/change
   --no-install                    Skip dependency installation
   --yes, -y                       Apply recommended edits without prompts
   --help, -h                      Show this help message