@devalok/shilp-sutra 0.40.1 → 0.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devalok/shilp-sutra",
-  "version": "0.40.1",
+  "version": "0.42.0",
   "description": "Devalok Design System — accessible React components, OKLCH design tokens, and Tailwind 4 CSS-first setup. Ships with AI-agent setup recipes.",
   "license": "MIT",
   "author": "Devalok Design & Strategy Studios <shilp-sutra@devalok.in>",
@@ -65,6 +65,8 @@
     },
     "./css": "./dist/tokens/shilp-sutra.css",
     "./tokens": "./dist/tokens/index.css",
+    "./BREAKING.json": "./BREAKING.json",
+    "./BREAKING.schema.json": "./BREAKING.schema.json",
     "./ui": {
       "types": "./dist/ui/index.d.ts",
       "import": "./dist/ui/index.js",
@@ -791,7 +793,9 @@
       "import": "./dist/ai/types.js",
       "default": "./dist/ai/types.js"
     },
-    "./docs/*": "./docs/components/*"
+    "./docs/*": "./docs/components/*",
+    "./make-kit": "./make-kit/Guidelines.md",
+    "./make-kit/*": "./make-kit/*"
   },
   "files": [
     "dist",
@@ -799,9 +803,12 @@
     "docs/recipes",
     "docs/rollback.md",
     "fonts",
+    "make-kit",
     "skill",
     "scripts/welcome.mjs",
     "AGENTS.md",
+    "BREAKING.json",
+    "BREAKING.schema.json",
     "MIGRATION.md",
     "README.md",
     "llms.txt",

package/skill/SKILL.md

@@ -3,7 +3,7 @@ name: shilp-sutra
 description: Add, configure, and use components from Devalok's shilp-sutra design system (@devalok/shilp-sutra) — a Tailwind 4 + React 19 + CVA library with 110+ accessible components, OKLCH design tokens, framer-motion animations, and per-component RSC-safe entry points. Use this skill whenever the user mentions shilp-sutra, Devalok, the @devalok npm scope, or asks to install/add/style/theme UI in any React project that already depends on the package — even if they don't name it explicitly. Use it instead of generic shadcn/ui, MUI, or Chakra knowledge when shilp-sutra is in the project. Covers Next.js (App + Pages), Vite, Astro, Remix, TanStack Start setup playbooks; component API and variant reference; brand token customization; Server Component import patterns; and a troubleshoot tree for the thirteen most common breakages.
 license: MIT
 metadata:
-  version: "0.40.1"
+  version: "0.42.0"
   author: Devalok Design & Strategy Studios
   homepage: https://github.com/devalok-design/shilp-sutra
   npm: https://www.npmjs.com/package/@devalok/shilp-sutra
@@ -64,8 +64,8 @@ These are non-negotiable. Violating any of them produces runtime errors that loo
    ```
 2. **`framer-motion@^12` is a required peer dep.** The consumer must install it. Module-scoped contexts (`MotionConfig`, `LayoutGroup`, `AnimatePresence`) silently break if two copies of framer-motion resolve. Configure pnpm/yarn to dedupe.
 3. **`sonner@^2` is an optional peer dep.** Install only when rendering `<Toaster />`.
-4. **Per-component imports are mandatory for React Server Components.** `@devalok/shilp-sutra/ui/text` is server-safe; the barrel `@devalok/shilp-sutra/ui` pulls client code and crashes RSC. See `references/server-components.md` for the per-component matrix.
-5. **Spacing namespace is `--spacing-ds-*`.** Write `p-ds-04`, not `p-4`. Same for typography: `text-ds-body-md`, not `text-base`.
+4. **Prefer per-component imports — they keep RSC bundles small and avoid peer-dep cliffs.** `@devalok/shilp-sutra/ui/text` is server-safe and pulls only its own peers. The barrel `@devalok/shilp-sutra/ui` re-exports every component (including ones with hard peer deps like `input-otp`), so it forces those peers to install even when unused. With all peers installed the barrel also works in RSC (per-component `"use client"` is honoured), but the client bundle is larger. Prefer per-component for new code; existing barrel usage is not an emergency. See `references/server-components.md`.
+5. **Spacing uses the `--spacing-ds-*` namespace** (`p-ds-04`, `gap-ds-03`); typography uses `text-ds-body-md`. These **coexist with** Tailwind 4's numeric scale (`p-4`, `gap-2`) by design — both valid. Pick `p-ds-*` for values that should track DS theme changes, `p-N` for one-off layout. Do NOT mass-codemod `p-4` → `p-ds-04`. **Cadence when building layouts:** pick a 3-tier scale, not every adjacent token — `ds-03` (related: label↔field), `ds-05` (grouped: between field-groups), `ds-07` (section: between blocks), optional `ds-08`+ (hero). 3-4 distinct gaps per surface; 5+ reads muddy. Anti-pattern: `ds-02` + `ds-04` as different signals on one surface — they collapse. The squint test must still reveal grouping.
 6. **Bare `shadow` does not exist in Tailwind 4.** Use `shadow-raised`, `shadow-overlay`, `shadow-floating`. Bare `rounded` is fine (maps to `--radius`); `rounded-ds-lg` etc. for sized variants.
 7. **Do not invent variant names.** CVA source files at `node_modules/@devalok/shilp-sutra/dist/ui/*.d.ts` (or `packages/core/src/ui/*.tsx` in the DS repo) are authoritative. When in doubt, check `references/components-full.md` for the enumerated list. If you guess a variant that doesn't exist, the prop is silently dropped and the default applies.
 8. **Default `variant="soft"` over `variant="outline"` for non-primary Button actions.** Soft (tinted bg + tinted text, no border) reads warmer in data-dense UIs. Use outline only when soft would disappear on a colored background or when a primary/secondary hierarchy needs a visible border.

package/skill/references/components-full.md

@@ -7,7 +7,7 @@
 > All variant values and props verified from source CVA definitions.
 >
 > Package: @devalok/shilp-sutra
-> Version: 0.40.1
+> Version: 0.42.0
 >
 > **If you are an AI agent reading this file top-to-bottom:** the Setup
 > section below is authoritative. If any later per-component doc or a

package/skill/references/components.md

@@ -51,6 +51,7 @@ The repo URL for these files is `https://github.com/devalok-design/shilp-sutra/t
 - **Agent-friendly install experience.** `AGENTS.md` now ships in the tarball (`node_modules/@devalok/shilp-sutra/AGENTS.md`), discoverable by 25+ agent tools. `package.json` declares an `agents` field (npm-agentskills convention) so `pnpm dlx @codemcp/agentskills export` auto-installs the bundled skill. New postinstall welcome banner (silent in CI / non-TTY / `SHILP_SUTRA_NO_WELCOME=1`). `troubleshoot.md` gained peer-cliff symptom entries.
 - **`llms-quick.txt`.** New ≤15K-token fast-path summary in the tarball — fits in one Read on any agent. Read order is now `llms-quick.txt` → `llms.txt` → `llms-full.txt`.
 - **Companion package `@devalok/eslint-plugin-shilp-sutra`** (first release). 12 rules — deprecated-API catches, peer-cliff barrel-import detection, TW3→TW4 classname autofixes. `pnpm add -D @devalok/eslint-plugin-shilp-sutra`, then `shilpSutra.configs['flat/recommended']`. Three presets: `recommended`, `strict`, `migration` (one-shot codemod).
+- **Machine-readable `BREAKING.json` manifest** (v0.40.2+). Structured record of every breaking change per version (moves, narrowings, removals, renames). At `node_modules/@devalok/shilp-sutra/BREAKING.json` after install; subpath export `@devalok/shilp-sutra/BREAKING.json`. AI agents and migration tooling read this instead of parsing CHANGELOG prose. Schema at `BREAKING.schema.json`. Pre-publish-audit gate enforces a manifest entry for every release with a breaking CHANGELOG signal.
 
 ## BREAKING CHANGES (v0.40.0)
 

package/skill/references/setup-next-app-router.md

@@ -4,6 +4,8 @@
 
 > Setup recipe for adding `@devalok/shilp-sutra` to a Next.js 13+ App Router project.
 
+> **Tested cold-install on:** Next 16.2.6 + React 19.2 + Turbopack + pnpm 10.30 + Node 22 + Windows 11 (2026-05-25). Earlier versions of Next 13/14/15 are still supported on this recipe; deltas called out inline.
+
 ## 1. Detect the framework
 
 You are in this recipe if **all** of these are true:
@@ -61,27 +63,35 @@ Some components depend on third-party libraries that ship as optional peers. **I
 
 ## 3. Configure PostCSS
 
-Create or update `postcss.config.mjs` at the project root:
+**Next 14+ scaffolds this for you.** Verify `postcss.config.mjs` (or `.js` / `.cjs` / `.json`) at the project root contains:
 
 ```js
-export default {
+const config = {
   plugins: {
     "@tailwindcss/postcss": {},
   },
 };
+
+export default config;
 ```
 
-If a `postcss.config.{js,cjs,json}` already exists, merge the plugin in. Do not delete the existing file.
+If the file is missing, create it with the contents above. If another PostCSS file exists with different plugins, merge `@tailwindcss/postcss` in — do not delete the existing file.
 
 ## 4. Wire Tailwind 4 + design tokens
 
-Locate the global CSS file. Common paths in priority order:
+### 4a. Locate the global CSS file
+
+Next 13+ default location depends on the `--src-dir` choice at scaffold time:
+
+- `src/app/globals.css` — default since Next 14 when scaffolded without `--src-dir false`. **Most common in Next 16+ defaults.**
+- `app/globals.css` — when scaffolded with `--src-dir false` (no `src/`).
+- `app/global.css` — older Next 13 scaffolds.
 
-- `app/globals.css`
-- `src/app/globals.css`
-- `app/global.css`
+If none exists, create at whichever path matches the project's existing `app/` location.
 
-If none exists, create `app/globals.css`. Set the file contents to (or merge into):
+### 4b. Replace the scaffold's CSS with the shilp-sutra setup
+
+A fresh `create-next-app` scaffold writes a `globals.css` with `:root` color vars, an `@theme inline` block linked to Geist font vars, a `prefers-color-scheme` dark override, and a `body { font-family: Arial }` block. **Replace the entire file** with the shilp-sutra setup unless you have a specific reason to keep scaffold styles:
 
 ```css
 @import "tailwindcss";
@@ -90,7 +100,11 @@ If none exists, create `app/globals.css`. Set the file contents to (or merge int
 
 **Order matters.** `tailwindcss` MUST come first. The shilp-sutra `/css` entry registers `@theme` blocks that the Tailwind import must process.
 
-If the project has its own theme overrides, place them AFTER both imports:
+If you want to keep the scaffold's color/font vars alongside shilp-sutra tokens (rare — usually you want one or the other), put scaffold's `@theme inline` / `:root` / `body` blocks AFTER the shilp-sutra import. Otherwise the scaffold's `body { font-family: Arial }` will compete with shilp-sutra's font setup.
+
+### 4c. Optional: add your own theme overrides
+
+Place after both imports:
 
 ```css
 @import "tailwindcss";
@@ -101,12 +115,16 @@ If the project has its own theme overrides, place them AFTER both imports:
 }
 ```
 
-Import the CSS file once from `app/layout.tsx` (it should already be imported in a fresh `create-next-app` project):
+### 4d. Ensure CSS is imported from the layout
+
+The CSS import in `app/layout.tsx` (or `src/app/layout.tsx`) should already exist in a fresh scaffold:
 
 ```tsx
 import "./globals.css";
 ```
 
+If you removed the Geist-font import from layout.tsx (see § 6), keep this CSS import line.
+
 ## 5. Configure `transpilePackages`
 
 Edit `next.config.{ts,js,mjs}`. Add the `transpilePackages` field:
@@ -125,6 +143,8 @@ If a `transpilePackages` array already exists, append to it. Do not replace.
 
 Without `transpilePackages`, Next will refuse to load our pre-built `dist/*.js` because it ships native ESM that does not match Next's CJS-leaning loader for `node_modules`.
 
+**Turbopack:** as of Next 16, Turbopack is the default bundler (`next dev` and `next build`). `transpilePackages` is respected by both Turbopack and the Webpack backend. Tested on Turbopack 16.2 cold-install (2026-05-25); no extra config needed.
+
 ## 6. Scaffold the Providers wrapper
 
 Create `app/providers.tsx`:
@@ -151,13 +171,21 @@ export function Providers({ children }: { children: ReactNode }) {
 - Drop the `Toaster` import and its JSX usage
 - Skip installing `sonner`
 
-Mount `<Providers>` from `app/layout.tsx`:
+Mount `<Providers>` from `app/layout.tsx` (or `src/app/layout.tsx`). **Replace the scaffold's layout** with the version below — the scaffold imports `next/font/google` (Geist) and applies font-variable classes to `<html>`, which you don't need when shilp-sutra ships its own fonts:
 
 ```tsx
+import type { Metadata } from "next";
 import "./globals.css";
 import { Providers } from "./providers";
 
-export default function RootLayout({ children }: { children: React.ReactNode }) {
+export const metadata: Metadata = {
+  title: "Your app",
+  description: "Built with shilp-sutra",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{ children: React.ReactNode }>) {
   return (
     <html lang="en" suppressHydrationWarning>
       <body>
@@ -168,11 +196,20 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
 
+Specifically, **remove these scaffold lines**:
+
+- `import { Geist, Geist_Mono } from "next/font/google";`
+- The `const geistSans = Geist({...})` and `const geistMono = Geist_Mono({...})` blocks
+- The `className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}` on `<html>`
+- The `className="min-h-full flex flex-col"` on `<body>`
+
+If you want to keep Geist alongside shilp-sutra's fonts, leave the `Geist` imports — but know that shilp-sutra's `font-sans` token resolves to Inter (body) and Ranade (display), not to the scaffold's `--font-geist-sans`. Loading both is wasted bytes.
+
 `suppressHydrationWarning` on `<html>` is required because `next-themes` writes the `class` attribute before React hydrates. Without it, every page logs a hydration warning.
 
 ## 7. Verify the install
 
-Replace the contents of `app/page.tsx`:
+Replace the contents of `app/page.tsx` (or `src/app/page.tsx`). The scaffold's `page.tsx` imports `next/image` and renders the Vercel marketing layout — replace the whole file:
 
 ```tsx
 import { Button } from "@devalok/shilp-sutra/ui/button";
@@ -211,6 +248,7 @@ If anything is off, see [troubleshoot.md](./troubleshoot.md).
 ## 8. Common gotchas
 
 - **CSS import order.** `tailwindcss` BEFORE `@devalok/shilp-sutra/css`. Reversing the order silently produces a build with no design-system utilities.
+- **Scaffold's `body { font-family: Arial }` overrides shilp-sutra fonts.** The `create-next-app` `globals.css` template sets `font-family: Arial, Helvetica, sans-serif` on `<body>`. If you kept the scaffold's body styles, they win the cascade over shilp-sutra's `font-sans`. § 4b says to replace the whole file — follow it.
 - **Multiple `framer-motion` copies.** Run `pnpm why framer-motion`. If it shows more than one resolved version, contexts (`MotionConfig`, `LayoutGroup`, `AnimatePresence`) silently break. Fix:
   ```jsonc
   // package.json
@@ -224,7 +262,9 @@ If anything is off, see [troubleshoot.md](./troubleshoot.md).
   ```
   For npm/yarn/bun equivalents, see [troubleshoot.md](./troubleshoot.md).
 - **Per-component imports keep RSC fast AND avoid peer-dep cliffs.** Inside Server Components, prefer `@devalok/shilp-sutra/ui/text`, `…/composed/page-header`, etc. The barrel `@devalok/shilp-sutra/ui` re-exports many client components — including some with hard peer-dep imports (e.g. `input-otp`) — so it both inflates the client bundle and forces those peers to be installed even when you never render those components. See [server-components.md](./server-components.md) for the full RSC-safety matrix.
-- **`p-3` vs `p-ds-03` — both are valid.** DS spacing uses the `--spacing-ds-*` namespace (`p-ds-04`, `gap-ds-03`); Tailwind 4's default numeric scale (`p-4`, `gap-2`) coexists by design. Pick `p-ds-*` for values that should track DS theme changes (card padding, form gaps); pick `p-N` for one-off layout values (section breathing room). Do NOT mass-codemod `p-4` → `p-ds-04` — that is not what the package intends.
+- **`p-3` vs `p-ds-03` — both are valid.** DS spacing uses the `--spacing-ds-*` namespace (`p-ds-04`, `gap-ds-03`); Tailwind 4's default numeric scale (`p-4`, `gap-2`) coexists by design. Pick `p-ds-*` for values that should track DS theme changes (card padding, form gaps); pick `p-N` for one-off layout values (section breathing room). Do NOT mass-codemod `p-4` → `p-ds-04` — that is not what the package intends. For layout rhythm, pick a 3-tier cadence (`ds-03` related / `ds-05` grouped / `ds-07` section), not every adjacent token.
+- **Auto-generated `pnpm-workspace.yaml`.** `pnpm 10+` writes a `pnpm-workspace.yaml` at the project root on first install with `ignoredBuiltDependencies` entries. This is harmless for a standalone app, but if you're nesting this project inside a larger monorepo, delete this file and use the parent monorepo's workspace config instead.
+- **Auto-generated `AGENTS.md`.** `create-next-app` writes an `AGENTS.md` with managed `<!-- BEGIN:nextjs-agent-rules -->` / `<!-- END:nextjs-agent-rules -->` markers. Shilp Sutra's agent rules use `<!-- BEGIN:shilp-sutra-agent-rules -->` markers — they coexist cleanly. If you install the shilp-sutra Agent Skill (see the repo root `AGENTS.md` for the one-liner), it adds its block alongside Next's, not over it.
 - **Bare `shadow` is dead.** Tailwind 4 has no `--shadow-DEFAULT`. Use `shadow-raised`, `shadow-overlay`, or `shadow-floating`.
 
 ## 9. What you should NOT do

package/skill/references/upgrading.md

@@ -18,6 +18,25 @@ A version bump is **not** safe-by-default. Breaking changes in this design syste
 
 ## Step 2 — find affected call sites in your code
 
+**Fastest path — read the machine-readable manifest:**
+
+```bash
+# Lists every break per version as structured data (moves, narrowings, removals)
+cat node_modules/@devalok/shilp-sutra/BREAKING.json
+```
+
+Or programmatically:
+
+```js
+import manifest from '@devalok/shilp-sutra/BREAKING.json'
+// manifest.versions["0.40.0"].moved        → [{ symbol, from, to, peer, eslintRule }, …]
+// manifest.versions["0.40.0"].narrowed     → [{ prop, components, from, to, fix }, …]
+```
+
+Schema: `@devalok/shilp-sutra/BREAKING.schema.json`. AI agents should prefer this over prose-parsing CHANGELOG.
+
+**Or grep manually:**
+
 ```bash
 # Symbols moved out of barrels (0.40.0 peer-cliff cleanup example):
 grep -rn "from '@devalok/shilp-sutra/ui'" src/ | grep -E "Toaster|toast|InputOTP"