@actioneer/ads 1.0.5 → 1.0.6

package/DESIGN.md

@@ -179,7 +179,7 @@ components:
 
 TASTE.md puts it in one line: On a quiet, neutral ground, colour and motion are spent like money — rarely, deliberately, and only where the eye should go.
 
-ADS 1.0.5 is a library first and a look second. 323 components across 10 families (Primitives / utilities, Foundations, Form controls, Overlays, Data display, Feedback, Navigation, Layout, AI Elements, Chat) ship from one barrel, and every product that consumes them inherits the judgment encoded in 56 semantic tokens and 11 principles rather than re-deciding it per screen.
+ADS 1.0.6 is a library first and a look second. 323 components across 10 families (Primitives / utilities, Foundations, Form controls, Overlays, Data display, Feedback, Navigation, Layout, AI Elements, Chat) ship from one barrel, and every product that consumes them inherits the judgment encoded in 56 semantic tokens and 11 principles rather than re-deciding it per screen.
 
 The ground is warm grey and the ink is warm near-black. One hue is spent by default, the Studio teal CTA family, and four more carry semantic status. Everything else stays neutral. A consumer product may narrow that further, and one already does: Baby Sentinel drops the teal and runs every action on ink.
 

package/README.md

@@ -0,0 +1,205 @@
+# @actioneer/ads
+
+The **Actioneer Design System**: React 19 components, Tailwind CSS v4 tokens,
+bundled Aribau Grotesk fonts, and accessible interactions with built-in motion.
+
+[Browse components in Storybook](https://actioneer-ads-storybook.himanshu-563.workers.dev).
+
+> **The one rule:** build UI **only** from the exact named exports of
+> `@actioneer/ads`, and reference tokens — never raw color/dimension literals.
+> Never fork, alias, deep-import, or hand-roll a copy of a component.
+> `@actioneer/ads-lint` enforces this.
+
+---
+
+## 1. Install
+
+```bash
+npm install @actioneer/ads motion
+```
+
+Use an existing **React 19 + Tailwind CSS v4** application with an ESM-capable
+bundler. `react` and `react-dom` are peer dependencies; the application owns the
+React instance. The setup below uses Next.js App Router paths.
+
+The bootstrap configures styles and providers and creates the lint config:
+
+```bash
+npx @actioneer/ads init
+```
+
+`init` adds the CSS import, creates `ads-providers.tsx` (or `.jsx`), and writes a
+consumer `ads-lint.config.mjs`. It wraps detected Next.js layouts and reports any
+manual setup still needed. Run it from your application directory after setting
+up Tailwind v4. The manual setup follows.
+
+## 2. Tailwind v4 + `styles.css` (import order matters)
+
+In your global stylesheet, import ADS's stylesheet **immediately after**
+Tailwind:
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@import "@actioneer/ads/styles.css";
+```
+
+`styles.css` carries three things that must live in the **same CSS graph** as
+`tailwindcss`:
+
+- the `@theme` **design tokens** (colors, typography, spacing, and radii),
+- the **Aribau Grotesk** `@font-face` rules (served package-relative — no
+  `/public` copy needed), and
+- a baked `@source "./**/*.{js,mjs}"` so Tailwind scans ADS's own class usage and
+  generates its utilities in your build.
+
+> ⚠️ Import order is load-bearing. If you `@import "@actioneer/ads/styles.css"`
+> **before** `@import "tailwindcss"` — or import it into a stylesheet that isn't
+> part of the Tailwind graph — its `@theme` is an unknown at-rule and **no tokens
+> emit** (you'll get an unstyled, "blank" render).
+
+Granular entries are also exported if you need them: `@actioneer/ads/theme.css`
+(tokens only) and `@actioneer/ads/fonts.css` (`@font-face` only).
+
+## 3. Required providers
+
+Wrap your app root **once** with all three providers. `npx @actioneer/ads init`
+generates this as `app/ads-providers.tsx` (beside the layout when using `src/app`):
+
+```tsx
+// app/ads-providers.tsx
+"use client";
+
+import type { ReactNode } from "react";
+import { TooltipProvider, ToastProvider } from "@actioneer/ads";
+import { MotionConfig } from "motion/react";
+
+export function Providers({ children }: { children: ReactNode }) {
+  return (
+    <MotionConfig reducedMotion="user">
+      <ToastProvider>
+        <TooltipProvider>{children}</TooltipProvider>
+      </ToastProvider>
+    </MotionConfig>
+  );
+}
+```
+
+```tsx
+// app/layout.tsx
+import type { ReactNode } from "react";
+import { Providers } from "./ads-providers";
+import "./globals.css";
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body><Providers>{children}</Providers></body>
+    </html>
+  );
+}
+```
+
+- **`TooltipProvider`** — required. The vendored tooltip/attachment chips crash
+  the tree without an ancestor provider.
+- **`ToastProvider`** — required to render toasts.
+- **`<MotionConfig reducedMotion="user">`** — honors the OS reduced-motion
+  setting across every ADS animation.
+
+For other React frameworks, import the global stylesheet and wrap the application
+root with `Providers` in the framework's entry point.
+
+## 4. Usage
+
+Import the **exact named export** from the package barrel:
+
+```tsx
+// app/page.tsx
+"use client";
+
+import { Button, InputField } from "@actioneer/ads";
+
+export default function Example() {
+  return (
+    <main className="mx-auto flex max-w-sm flex-col gap-4 p-6">
+      <InputField label="Workspace name" defaultValue="Actioneer" />
+      <div className="flex gap-2">
+        <Button variant="solid" size="md">Save</Button>
+        <Button variant="secondary">Cancel</Button>
+      </div>
+    </main>
+  );
+}
+```
+
+Do **not**:
+
+| ❌ Anti-pattern | ✅ Instead |
+|----------------|-----------|
+| `import { Button } from "@actioneer/ads/button"` (deep import) | `import { Button } from "@actioneer/ads"` |
+| `import { Card as Panel } from "@actioneer/ads"` (alias) | use the export's real name, `Card` |
+| `import Button from "@actioneer/ads"` (default) / `import * as ADS` (namespace) | named imports only |
+| copy a component's source into your repo and edit it (fork) | import it; request an ADS change upstream |
+| `class="bg-[#0a0a0b]"` / `"#0a0a0b"` (literal) | a semantic token, e.g. `bg-brand` |
+| `import { Dialog } from "@radix-ui/react-dialog"` (external UI) | the ADS primitive (`Modal`, `Popover`, …) |
+
+**Why:** ADS is a single source of truth. A token or motion fix ships to the
+whole fleet with one version bump — but only if every consumer imports the
+canonical export instead of a divergent fork.
+
+**Discover exact names:** the machine-readable catalog ships in the package —
+`@actioneer/ads/manifest.json` (every export → name, family, kind, variants,
+props, showcase URL) and `@actioneer/ads/llms.txt` (the LLM-facing index). Point
+your coding agent at those, or use the ADS MCP server.
+
+Reference the semantic tokens (e.g. `bg-brand`, `text-muted-foreground`,
+`border-input`, `ring-ring`) rather than raw values; the full token list is in
+`manifest.json` under `tokens`.
+
+Shared motion presets are named exports from `@actioneer/ads`. Components already
+include their own interaction motion; use the exported presets for additional
+application state changes.
+
+## 5. Wire up `ads-lint`
+
+`@actioneer/ads-lint` enforces the contract above on your changed files.
+
+```bash
+npm install -D @actioneer/ads-lint typescript
+```
+
+Drop a **consumer-mode** config at your repo root (`init` writes this for you):
+
+```js
+// ads-lint.config.mjs
+export default {
+  imports: {
+    libraryPackage: "@actioneer/ads",
+    libraryRoot: null, // consumer mode: every file is a consumer
+  },
+};
+```
+
+Run it:
+
+```bash
+# lint everything
+npx ads-lint --all
+# or just what changed (pre-commit / CI)
+npx ads-lint --staged
+npx ads-lint --diff origin/main
+```
+
+It flags deep imports, aliased/default/namespace barrel imports, external-UI
+imports, hardcoded color/dimension literals, and banned/weak motion — the same
+rules ADS holds itself to. A CI job that runs `npx ads-lint --diff <base>` keeps
+every consuming repo honest.
+
+## Documentation and license
+
+- [Storybook: components and recipes](https://actioneer-ads-storybook.himanshu-563.workers.dev)
+- [ADS MCP: component discovery for coding agents](https://www.npmjs.com/package/@actioneer/ads-mcp)
+- Bundled references: `@actioneer/ads/manifest.json`, `@actioneer/ads/llms.txt`,
+  and `@actioneer/ads/DESIGN.md`.
+
+MIT licensed.

package/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "@actioneer/ads",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "importPath": "@actioneer/ads",
   "styleImport": "@import \"@actioneer/ads/styles.css\";",
   "families": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actioneer/ads",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Actioneer Design System 1.0 — React 19 + Tailwind v4 component library.",
   "type": "module",
   "sideEffects": [