@devalok/shilp-sutra 0.37.1 → 0.39.0

package/skill/SKILL.md

@@ -0,0 +1,144 @@
+---
+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 eight most common breakages.
+license: MIT
+metadata:
+  version: "0.38.0"
+  author: Devalok Design & Strategy Studios
+  homepage: https://github.com/devalok-design/shilp-sutra
+  npm: https://www.npmjs.com/package/@devalok/shilp-sutra
+  source: https://github.com/devalok-design/shilp-sutra/tree/main/skills/shilp-sutra
+---
+
+# shilp-sutra — Devalok Design System
+
+`@devalok/shilp-sutra` is a React design system. It is **not** shadcn/ui. It uses similar primitives (Radix, CVA, Tailwind) but the consumer setup, token namespace, and component APIs are different. Your training data is older than the current package — read the bundled references before writing code, do not improvise from memory.
+
+## When this skill triggers
+
+- The user mentions `shilp-sutra`, `@devalok`, Devalok, or Devalok's design system.
+- The project's `package.json` lists `@devalok/shilp-sutra` (or `@devalok/shilp-sutra-brand`).
+- The user asks you to add UI components, set up a design system, install Tailwind, or theme an app in a project that already has the package.
+- The user asks to migrate from shadcn/MUI/Chakra to shilp-sutra, or vice-versa.
+
+## Decision tree (read this first, then jump)
+
+```
+Q1. Is @devalok/shilp-sutra already installed?
+    NO  → go to "First-time setup" below
+    YES → continue
+
+Q2. What does the user want to do?
+    a) Add or use a component        → references/components.md (skim), then components-full.md (deep)
+    b) Change colors/fonts/radius    → references/customize-brand.md
+    c) Server Components / Next.js   → references/server-components.md
+    d) Something is broken           → references/troubleshoot.md
+    e) Upgrading from older version  → fetch MIGRATION.md from repo or node_modules
+```
+
+## First-time setup
+
+Detect the framework from the consumer's lockfile and config files, then open the matching reference:
+
+| Detection                                                          | Reference                                |
+| ------------------------------------------------------------------ | ---------------------------------------- |
+| `app/` directory + `next.config.*`                                 | `references/setup-next-app-router.md`    |
+| `pages/` directory (no `app/`) + `next.config.*`                   | `references/setup-next-pages.md`         |
+| `vite.config.*` + `react` in deps (no Remix/TanStack)              | `references/setup-vite.md`               |
+| `astro.config.*`                                                   | `references/setup-astro.md`              |
+| `remix.config.*` or Remix v2 with Vite                             | `references/setup-remix.md`              |
+| `app.config.*` with `@tanstack/start`                              | `references/setup-tanstack-start.md`     |
+| Anything else (React + Tailwind)                                   | Fall back to `setup-vite.md` and adapt   |
+
+Every line in those recipes is there because skipping it broke a real consumer. Do not paraphrase steps — execute them.
+
+## Hard constraints (these silently break things if violated)
+
+These are non-negotiable. Violating any of them produces runtime errors that look unrelated to the design system.
+
+1. **Tailwind 4 only.** Do not create `tailwind.config.ts` with `presets: [shilpSutra]`. The JS preset was removed in 0.38. Setup is CSS-only:
+   ```css
+   @import "tailwindcss";
+   @import "@devalok/shilp-sutra/css";
+   ```
+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`.
+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.
+
+## Surface layering (when building cards, panels, dialogs)
+
+The semantic surface names are the public API. The old numeric names (`surface-1` … `surface-4`) are deprecated aliases — do not use them.
+
+| Token                          | Use for                                                                            |
+| ------------------------------ | ---------------------------------------------------------------------------------- |
+| `bg-surface-base`              | Page background                                                                    |
+| `bg-surface-raised`            | Cards, widgets, panels — anything that sits **on** the page                        |
+| `bg-surface-sunken`            | Shell chrome (Sidebar, TopBar), recessed regions                                   |
+| `bg-surface-overlay`           | Dialog, Sheet, Popover, Toast, Combobox menus, any floating overlay                |
+| `bg-surface-raised-hover`      | Hover state on raised surfaces                                                     |
+| `bg-surface-raised-active`     | Active/pressed state on raised surfaces                                            |
+| `bg-surface-disabled`          | Disabled surfaces (paired with `text-surface-fg-disabled`)                         |
+| `bg-surface-inverted`          | Inverted surfaces (dark on light themes, light on dark themes)                     |
+
+Putting `bg-surface-base` on a card is a bug — cards belong on `surface-raised`. The pre-publish audit in the DS repo enforces this and blocks the old numeric aliases in component source files.
+
+## Adding a component
+
+1. Skim `references/components.md` — the concise cheatsheet, ~660 lines. Tells you what exists, what variants ship, what the common gotchas are.
+2. If `components.md` does not have enough detail (you need full prop tables, every variant, every example), open `references/components-full.md`.
+3. Import from the per-component entry: `import { Button } from "@devalok/shilp-sutra/ui/button"`. The barrel `@devalok/shilp-sutra/ui` works in client-only contexts but is heavier — prefer per-component.
+4. Use **semantic tokens** for color (`text-foreground`, `bg-surface-2`, `border-border-default`). Never raw OKLCH values, never `text-white`.
+5. Compose with primitives the package already ships. Do not rebuild Dialog/Popover/Combobox from scratch.
+
+## Theming and brand customization
+
+`references/customize-brand.md` covers token overrides — color ramps, radius, font swap, spacing scale, dark-mode mapping. Customization is CSS-only: override CSS custom properties under `:root` and `.dark`. There is no theme provider component.
+
+For the Devalok logo and other brand assets, the sibling package `@devalok/shilp-sutra-brand` ships SVG + PNG. Install it separately.
+
+## Server Components and import patterns
+
+`references/server-components.md` has the per-component RSC-safety matrix. The short version:
+
+- Layout, typography, and presentational components (`Text`, `Heading`, `Card`, `Container`, `Stack`) → server-safe.
+- Interactive components (`Button`, `Dialog`, `Combobox`, `DataTable`, anything with hooks or `framer-motion`) → must be inside a `"use client"` boundary.
+- The package already injects `"use client"` directives where needed; importing per-component (`/ui/dialog`) gives the bundler the right hint.
+- Next.js consumers must add `transpilePackages: ["@devalok/shilp-sutra", "@devalok/shilp-sutra-brand"]` to `next.config.*`.
+
+## When something breaks
+
+Go straight to `references/troubleshoot.md`. It is a decision tree for the 8 most common breakages: Tailwind not detecting tokens, framer-motion duplicates, missing `transpilePackages`, wrong CSS import order, dark mode not toggling, RSC import errors, font 404s, hydration mismatches.
+
+Do not guess — most of these failures look identical from the outside but have different root causes. The tree disambiguates.
+
+## Browsing the system
+
+- **Storybook** (live previews, every story, MCP server available when running locally): https://devalok-design.github.io/shilp-sutra/
+- **Component reference (this skill)**: `references/components.md` (cheatsheet) and `references/components-full.md` (full API).
+- **Source**: https://github.com/devalok-design/shilp-sutra — `packages/core/src/ui/*.tsx` are the CVA sources of truth.
+
+When the package is installed locally, the same content also ships in the npm tarball:
+
+- `node_modules/@devalok/shilp-sutra/llms.txt` — cheatsheet
+- `node_modules/@devalok/shilp-sutra/llms-full.txt` — full reference
+- `node_modules/@devalok/shilp-sutra/docs/recipes/` — setup recipes
+- `node_modules/@devalok/shilp-sutra/skill/` — this skill (offline-installable)
+
+## Reporting feedback
+
+If a recipe is wrong, a constraint above is no longer accurate, or a component behavior contradicts the docs:
+
+1. File a GitHub issue at https://github.com/devalok-design/shilp-sutra/issues with the label `ai-agent-feedback`.
+2. Include the package version (`pnpm view @devalok/shilp-sutra version` or read from the consumer's lockfile), the file/recipe path, the exact command or error, and what you expected.
+
+## Stay current
+
+`@devalok/shilp-sutra` ships breaking changes during `0.x`. Before writing code:
+
+1. Check the installed version: `cat node_modules/@devalok/shilp-sutra/package.json | grep version` (or read from the consumer's lockfile).
+2. If the version is older than the metadata `version` field at the top of this SKILL.md, suggest the user upgrade and consult `MIGRATION.md` from the package root.
+3. Never trust APIs you remember from earlier versions — re-check `components.md` against the installed version.

package/skill/install.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# Install the shilp-sutra Agent Skill into ~/.claude/skills (or $INSTALL_DIR).
+#
+# Usage:
+#   curl -fsSL https://raw.githubusercontent.com/devalok-design/shilp-sutra/main/skills/shilp-sutra/install.sh | bash
+#
+# Custom install dir (e.g. project-scoped):
+#   curl -fsSL ... | INSTALL_DIR=.claude/skills bash
+
+set -euo pipefail
+
+REPO="devalok-design/shilp-sutra"
+BRANCH="${BRANCH:-main}"
+INSTALL_DIR="${INSTALL_DIR:-$HOME/.claude/skills}"
+SKILL_NAME="shilp-sutra"
+DEST="$INSTALL_DIR/$SKILL_NAME"
+
+if [[ -d "$DEST" ]]; then
+  echo "warning: $DEST already exists. Overwriting."
+  rm -rf "$DEST"
+fi
+
+mkdir -p "$DEST/references"
+
+# Fetch the skill tree via the GitHub trees API and download each file.
+echo "Fetching skill manifest from github.com/$REPO@$BRANCH ..."
+tree_json="$(curl -fsSL "https://api.github.com/repos/$REPO/git/trees/$BRANCH?recursive=1")"
+
+# Extract every path under skills/shilp-sutra/ that is a blob.
+paths="$(printf '%s\n' "$tree_json" \
+  | python3 -c '
+import json, sys
+tree = json.load(sys.stdin).get("tree", [])
+for item in tree:
+    if item.get("type") == "blob" and item.get("path", "").startswith("skills/shilp-sutra/"):
+        # Skip the install.sh itself when bootstrapping; user already has it via curl.
+        if item["path"].endswith("/install.sh"):
+            continue
+        print(item["path"])
+')"
+
+if [[ -z "$paths" ]]; then
+  echo "error: no files found under skills/shilp-sutra/ on $REPO@$BRANCH" >&2
+  exit 1
+fi
+
+count=0
+while IFS= read -r path; do
+  rel="${path#skills/shilp-sutra/}"
+  target="$DEST/$rel"
+  mkdir -p "$(dirname "$target")"
+  curl -fsSL "https://raw.githubusercontent.com/$REPO/$BRANCH/$path" -o "$target"
+  count=$((count + 1))
+done <<< "$paths"
+
+echo
+echo "installed $count files to $DEST"
+echo "restart Claude Code (or open a new session) to pick up the skill."
+echo "verify with: ask Claude 'what skills are available?'"