uidex 0.2.1 → 0.2.4

package/README.md

@@ -1,6 +1,6 @@
 # uidex
 
-A framework-agnostic library for highlighting and annotating UI elements. Works with React, vanilla JS, or any framework. Includes a build-time scanner, inspect mode, Playwright integration, and Claude Code tooling.
+A framework-agnostic library for highlighting and annotating UI elements. Works with React, vanilla JS, or any framework. Includes a build-time scanner, annotation linting, inspect mode, Playwright integration, and Claude Code tooling.
 
 ## Installation
 
@@ -96,7 +96,7 @@ The scanner finds `data-uidex` attributes in your source files and generates a t
 
 ```bash
 npx uidex scan           # Generate registry
-npx uidex scan --check   # Validate UIDEX_PAGE.md coverage
+npx uidex scan --audit   # Validate coverage and annotations
 ```
 
 Add it to your build:
@@ -117,6 +117,7 @@ Add it to your build:
   <a href="/">Home</a>
 </nav>
 
+{/* Optional: add a JSDoc description for richer documentation */}
 /** @uidex cta-button - Primary call-to-action button */
 <button data-uidex="cta-button">Click Me</button>
 ```
@@ -130,11 +131,12 @@ The scanner generates `src/uidex.gen.ts` (gitignored) with:
 - `ComponentId` — union type of all ids
 - `pages` — from `UIDEX_PAGE.md` files (directory-based component association)
 - `features` — from `UIDEX_FEATURE.md` files (explicit component association)
+- `uiComponents` — presentational primitives detected under `ui/` directories (see [UI Primitives](#ui-primitives))
 - Auto-registration calls
 
 ### Monorepo Support
 
-Use `sources` for multiple scan roots:
+The scanner auto-discovers multiple `.uidex.json` files in monorepo setups. Use `sources` for multiple scan roots within a single config:
 
 ```json
 {
@@ -149,6 +151,72 @@ Use `sources` for multiple scan roots:
 }
 ```
 
+## UI Primitives
+
+The scanner treats any `.tsx` file whose path contains a literal `ui/` segment as a presentational primitive (e.g. `components/ui/button.tsx`, `features/auth/ui/Form.tsx`). Primitives don't need `data-uidex` annotations — the scanner detects them by convention and emits a separate `uiComponents` array in `uidex.gen.ts` alongside the usual component map.
+
+Each primitive gets a **scope** resolved by walking up from its file:
+
+| Marker found first | Scope |
+|---|---|
+| `UIDEX_FEATURE.md` | `feature:<dir-name>` |
+| `UIDEX_PAGE.md` | `page:<dir-name>` |
+| neither | `global` |
+
+`npx uidex scan --audit` flags imports of feature- or page-scoped primitives from outside their scope tree. Global primitives are exempt.
+
+### Shape
+
+```ts
+import type { PrimitiveEntry } from 'uidex';
+
+// interface PrimitiveEntry {
+//   name: string;        // exported component name, e.g. "Button"
+//   filePath: string;    // source-root-relative path, e.g. "ui/button.tsx"
+//   scope: string;       // "global" | "feature:<name>" | "page:<name>"
+//   composes: string[];  // names of other primitives this one imports
+//   usedBy: string[];    // file paths of consumers (non-primitive sources)
+//   kind: 'ui';
+// }
+```
+
+`composes` and `usedBy` are filled in by a cross-source provenance pass, so you get the full dependency graph without maintaining it by hand. Barrel (`index.ts`) re-exports are **not** followed — import primitives directly from their source file for accurate tracking.
+
+### Building a custom catalog from `uiComponents`
+
+`uiComponents` is the public contract for building your own design-system docs page or component explorer. Import it from the generated file and render however you like:
+
+```tsx
+// app/gallery/page.tsx
+import { uiComponents } from '@/uidex.gen';
+import { Button } from '@/components/ui/button';
+
+// The only thing you maintain by hand: a map from primitive name to a live preview.
+const previews: Record<string, React.ReactNode> = {
+  Button: <Button>Click me</Button>,
+};
+
+export default function Gallery() {
+  return (
+    <ul>
+      {uiComponents.map((entry) => (
+        <li key={entry.filePath + entry.name}>
+          <h3>{entry.name} <small>({entry.scope})</small></h3>
+          <div>{previews[entry.name] ?? <em>no preview</em>}</div>
+          <p>Used by {entry.usedBy.length} file(s)</p>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+That's the whole pattern: **uidex ships the data, you ship the renderer.** Group by `scope` for sectioned layouts, filter on `composes`/`usedBy` to surface dependency graphs, or skip live previews entirely and render it as a plain data table.
+
+> **Note:** the `uiComponents` export is only present when the scanner finds at least one primitive. If your project has none yet, create a file under a `ui/` directory and re-run `npx uidex scan`.
+
+See [`examples/next-app/app/gallery/page.tsx`](./examples/next-app/app/gallery/page.tsx) for a worked example that groups primitives by scope and renders each with a live preview + `composes`/`usedBy` metadata.
+
 ## Components
 
 ### UidexDevtools (React)
@@ -160,6 +228,7 @@ import { UidexDevtools } from 'uidex';
 
 <UidexDevtools
   buttonPosition="bottom-right"
+  theme="auto"
   onSelect={(id) => console.log(id)}
 />
 ```
@@ -169,9 +238,12 @@ import { UidexDevtools } from 'uidex';
 | `components` | `UidexMap` | registry | Components map |
 | `config` | `UidexConfig` | - | Styling configuration |
 | `buttonPosition` | `ButtonPosition` | `'bottom-right'` | Initial button position |
+| `theme` | `UidexTheme` | `'auto'` | Theme: `'dark'`, `'light'`, or `'auto'` |
 | `disabled` | `boolean` | `false` | Disable devtools |
 | `onSelect` | `(id: string) => void` | - | Selection callback |
 | `inspectShortcut` | `KeyboardShortcut \| false` | `Shift+Cmd+U` | Inspect mode shortcut |
+| `ingest` | `IngestConfig` | - | Server feedback submission config |
+| `onSubmit` | `(report, result) => void` | - | Callback after feedback submission |
 
 ### UidexOverlay (React)
 
@@ -209,6 +281,7 @@ const ui = createUidexUI({
   features: [ ... ],
   config: { defaults: { color: '#3b82f6' } },
   buttonPosition: 'bottom-right',
+  theme: 'auto',
   inspectShortcut: { key: 'u', shiftKey: true, metaKey: true },
   onSelect: (id) => console.log(id),
 });
@@ -217,6 +290,37 @@ ui.mount();
 ui.destroy();
 ```
 
+## Theming
+
+The devtools widget supports automatic theme detection. Set `theme="auto"` (the default) to match the host page's theme — it checks for `.dark` / `.light` classes on `<html>` and falls back to the OS `prefers-color-scheme` media query. Changes are tracked live via `MutationObserver` and `matchMedia` listeners.
+
+```tsx
+// Auto-detect (default) — matches host page or OS preference
+<UidexDevtools theme="auto" />
+
+// Force dark or light
+<UidexDevtools theme="dark" />
+<UidexDevtools theme="light" />
+```
+
+All UI renders inside a Shadow DOM with CSS custom properties. The default theme is dark. Override tokens for a light theme:
+
+```css
+:root {
+  --background: #ffffff;
+  --foreground: #262626;
+  --card: #ffffff;
+  --card-foreground: #262626;
+  --popover: #ffffff;
+  --popover-foreground: #262626;
+  --primary: #262626;
+  --primary-foreground: #fafafa;
+  --muted: rgba(0, 0, 0, 0.04);
+  --muted-foreground: #6b6b6b;
+  --border: rgba(0, 0, 0, 0.08);
+}
+```
+
 ## Inspect Mode
 
 Press **Shift+Cmd+U** (Shift+Ctrl+U on Windows/Linux) to enter inspect mode. Hover over elements to highlight them, click to select. Press **Escape** to exit.
@@ -275,42 +379,21 @@ npx uidex scaffold [dir]
 
 ## Claude Code Integration
 
-Set up Claude Code with uidex-aware rules, a `/uidex-audit` skill, and a post-edit hook that validates coverage:
+Set up Claude Code with uidex-aware rules, a `/uidex:audit` skill, and a post-edit hook that validates coverage:
 
 ```bash
-npx uidex claude init       # Add rules + skill + hooks
-npx uidex claude teardown   # Remove everything
+npx uidex claude install    # Add rules + skill + hooks
+npx uidex claude uninstall  # Remove everything
 ```
 
 Manage individually:
 
 ```bash
 npx uidex claude rules add|remove    # .claude/rules/uidex.md
-npx uidex claude skill add|remove    # .claude/commands/uidex-audit.md
+npx uidex claude skill add|remove    # .claude/commands/uidex/audit.md
 npx uidex claude hooks add|remove    # PostToolUse hook in .claude/settings.json
 ```
 
-## Theming
-
-All UI renders inside a Shadow DOM with CSS custom properties. Override any token at `:root`:
-
-```css
-:root {
-  --uidex-color-primary: #2e2e2e;
-  --uidex-color-bg: #ffffff;
-  --uidex-color-bg-elevated: #f5f5f5;
-  --uidex-color-text: #1f2937;
-  --uidex-color-text-strong: #111827;
-  --uidex-color-text-muted: #6b7280;
-  --uidex-color-surface-hover: #f3f4f6;
-  --uidex-color-surface-active: #e5e7eb;
-  --uidex-color-border: #d1d5db;
-  --uidex-color-border-light: #e5e7eb;
-}
-```
-
-33 tokens available across colors, shadows, border-radius, z-index, typography, and transitions. The default theme is dark monochromatic with zero border-radius and monospace typography.
-
 ## Package Exports
 
 | Import | Description |
@@ -320,18 +403,26 @@ All UI renders inside a Shadow DOM with CSS custom properties. Override any toke
 | `uidex/react` | React wrappers (`UidexDevtools`, `UidexOverlay`) |
 | `uidex/playwright` | Test fixture and helpers |
 | `uidex/playwright/reporter` | Coverage reporter |
+| `uidex/api` | API client (Node.js) |
 | `uidex/styles.css` | Standalone CSS (optional, auto-injected via Shadow DOM) |
 
 ## CLI Reference
 
 ```
-npx uidex                    Initialize project (alias for init)
+npx uidex                    Show help / list commands
 npx uidex init               Create .uidex.json and update .gitignore
 npx uidex scan               Run component scanner
-npx uidex scan --check       Validate UIDEX_PAGE.md coverage
+npx uidex scan --audit       Validate coverage and annotations
 npx uidex scaffold [dir]     Generate Playwright test stubs
-npx uidex claude init        Set up Claude Code integration
-npx uidex claude teardown    Remove Claude Code integration
+npx uidex claude install     Set up Claude Code integration
+npx uidex claude uninstall   Remove Claude Code integration
+npx uidex login              Authenticate with uidex server
+npx uidex logout             Remove stored credentials
+npx uidex link               Link current directory to org/project
+npx uidex status             Show auth and link state
+npx uidex feedback           Manage feedback (list, show, update, delete)
+npx uidex triage             Manage triage (run, list, show, approve, dismiss, submit)
+npx uidex integrations       Manage integrations (list, add, remove, test, targets)
 ```
 
 ## TypeScript
@@ -346,10 +437,19 @@ import type {
   UidexLocation,
   UidexPage,
   UidexFeature,
+  UidexTheme,
+  UidexUIOptions,
+  PrimitiveEntry,
   BorderStyle,
   LabelPosition,
   ButtonPosition,
   KeyboardShortcut,
+  OverlayOptions,
+  IngestConfig,
+  FeedbackReport,
+  FeedbackResult,
+  FeedbackType,
+  FeedbackSeverity,
 } from 'uidex';
 ```
 

package/claude/audit-command.md

@@ -1,16 +1,46 @@
-Run `npx uidex scan --check` and fix all reported issues:
+Run `npx uidex scan --audit` and fix all reported issues:
 
-1. **Uncovered components** (components missing UIDEX_PAGE.md coverage):
-   - Create a `UIDEX_PAGE.md` in the nearest feature directory
-   - Include a heading, brief description, and acceptance criteria
+1. **Uncovered components** (components missing doc coverage):
+   - Create a `UIDEX_PAGE.md` in the component's directory for page-specific components
+   - For cross-cutting components (auth, billing, search, etc.), create or update a `UIDEX_FEATURE.md` in `features/<name>/` and list the component ID in the `components:` frontmatter
+   - Include a `# Title`, `> description` blockquote, and `## Acceptance` with `- [ ]` checkboxes
 
-2. **Orphaned UIDEX_PAGE.md files** (docs with no components underneath):
+2. **Route directories missing UIDEX_PAGE.md** (route with `page.tsx` but no doc):
+   - Create a `UIDEX_PAGE.md` in the route directory
+   - Without its own doc, the route's components get absorbed by a parent page doc
+
+3. **Orphaned UIDEX_PAGE.md files** (docs with no components underneath):
    - If the components were removed, delete the UIDEX_PAGE.md
-   - If components are missing `data-uidex` attributes, add them
+   - If components are missing annotations, add them
+
+4. **Orphaned UIDEX_FEATURE.md files** (features referencing no known components):
+   - Update the `components:` frontmatter to reference valid component IDs
+   - If the feature is no longer relevant, delete it
+
+5. **Missing descriptions** (pages/features without a `>` blockquote description):
+   - Add a `> description` blockquote immediately after the `# Title` heading
+
+6. **Missing block annotations** (structural regions):
+   - Add `data-uidex-block="kebab-id"` to page root wrappers and section containers
+   - Blocks do NOT need JSDoc comments
+
+7. **Missing interactive annotations**:
+   - Add `data-uidex="kebab-id"` to buttons, inputs, links, and other interactive elements
+   - Optionally add `/** @uidex id - description */` JSDoc above interactive elements
+
+8. **Primitive annotations** — use `data-uidex-primitive="kebab-name"` when a component is a **reusable presentational building block**, not a consumer/page component. Apply when ALL of these are true:
+   - The file **exports** a component (not a page or layout)
+   - The component **wraps native HTML elements or other primitives** (buttons, inputs, cards, badges) rather than composing app-level features
+   - The component is **imported by multiple consumers** or is designed to be reusable
+   - The component does **not fetch data or contain business logic** — it receives everything via props
+
+   Do NOT add `data-uidex-primitive` to:
+   - Page components, layouts, or route-level files
+   - Feature orchestrators (dialogs that compose multiple primitives with business logic)
+   - Components that call hooks for data fetching (`useQuery`, `useMutation`, etc.)
+   - One-off components only used in a single place (use `data-uidex` or `data-uidex-block` instead)
 
-3. **Review interactive elements** without `data-uidex` attributes:
-   - Scan modified files for buttons, inputs, links, and other interactive elements
-   - Add `data-uidex="kebab-id"` attributes where missing
-   - Add `/** @uidex id - description */` JSDoc above each annotated element
+   Files with `data-uidex-primitive` are exempt from missing-annotation lint checks.
+   The scanner detects primitives by the attribute alone — directory structure does not matter.
 
 After fixing all issues, run `npx uidex scan` to regenerate the component registry.

package/claude/rules.md

@@ -2,16 +2,63 @@
 
 This project uses [uidex](https://github.com/soel/uidex) for UI element tracking and documentation.
 
-## data-uidex attributes
+## Annotations
+
+uidex uses three annotation types:
+
+### `data-uidex` — interactive elements
+
+Every user-facing interactive element MUST have a `data-uidex="kebab-id"` attribute.
 
-- Every user-facing interactive element MUST have a `data-uidex="kebab-id"` attribute.
 - IDs should be descriptive and kebab-cased: `data-uidex="submit-btn"`, `data-uidex="user-avatar"`.
 - When creating new components with interactive elements, always add `data-uidex` attributes.
 - When modifying components, preserve existing `data-uidex` attributes. If you rename or remove an element, update or remove its attribute accordingly.
 
+### `data-uidex-block` — structural regions
+
+Structural UI regions (pages, sections, panels, toolbars) use `data-uidex-block="kebab-id"`.
+
+- Add `data-uidex-block` to the root wrapper of each page/component.
+- Add `data-uidex-block` to meaningful sections within a page (forms, tables, sidebars, etc.).
+- Blocks do NOT need JSDoc comments — they are spatial context, not documented behavior.
+
+```tsx
+<div data-uidex-block="settings-page">
+  <form data-uidex-block="settings-form">
+    /** @uidex save-btn - Saves current settings */
+    <button data-uidex="save-btn">Save</button>
+  </form>
+</div>
+```
+
+### `data-uidex-primitive` — reusable UI component definitions
+
+Reusable, presentational components (buttons, inputs, cards, etc.) use `data-uidex-primitive="kebab-name"` on the root element inside the component definition.
+
+- Place the attribute on the root element of the component's **definition**, not at call sites.
+- IDs should be descriptive and kebab-cased: `data-uidex-primitive="button"`, `data-uidex-primitive="sign-in-card"`.
+- A single element can carry both `data-uidex-primitive` and `data-uidex` without conflict.
+- Files containing `data-uidex-primitive` are exempt from missing-annotation lint checks.
+- Primitives do NOT need JSDoc comments — they are tracked by the scanner automatically.
+
+```tsx
+// Button.tsx — component definition
+export function Button({ children, ...props }) {
+  return <button data-uidex-primitive="button" {...props}>{children}</button>;
+}
+```
+
+### When to use which annotation
+
+| Annotation | Use for | Placed on |
+|---|---|---|
+| `data-uidex` | Interactive elements (buttons, inputs, links) | Usage sites in consumer components |
+| `data-uidex-block` | Structural regions (pages, forms, sections) | Wrapper elements in consumer components |
+| `data-uidex-primitive` | Reusable UI component definitions | Root element inside the component definition file |
+
 ## @uidex JSDoc comments
 
-Add a JSDoc comment above annotated elements describing their purpose:
+Add JSDoc comments above `data-uidex` (interactive) elements to enrich documentation. Do NOT add JSDoc to `data-uidex-block` elements.
 
 ```tsx
 /** @uidex submit-btn - Primary action button for form submission */
@@ -31,28 +78,43 @@ Multi-line format for longer descriptions:
 
 ## UIDEX_PAGE.md files
 
-Page docs describe a route/view. Components in the directory are automatically associated.
+Page docs describe a **route** (a URL the user can visit). Components in the directory are automatically associated.
 
-- Each page directory should have a `UIDEX_PAGE.md` with acceptance criteria.
-- When adding components to a directory that lacks a `UIDEX_PAGE.md`, create one.
-- When removing all components from a directory, remove its `UIDEX_PAGE.md`.
+- Place `UIDEX_PAGE.md` only in **route directories** (e.g., `app/settings/`, `app/dashboard/`, `app/(auth)/login/`).
+- Do NOT place `UIDEX_PAGE.md` in non-route directories like `contexts/`, `hooks/`, `lib/`, `utils/`, or shared `components/`.
+- Each route directory should have a `UIDEX_PAGE.md` with acceptance criteria.
+- The description MUST be a `>` blockquote immediately after the `# Title` heading.
+- Acceptance criteria MUST use `- [ ]` checkbox syntax.
+- When adding components to a route directory that lacks a `UIDEX_PAGE.md`, create one.
+- When removing all components from a route directory, remove its `UIDEX_PAGE.md`.
 
 ```markdown
 # Page Name
 
-Brief description of the page.
+> Brief description of what this page does and its purpose.
 
 ## Acceptance
-- User can do X
-- Y is displayed when Z
+- [ ] User can do X
+- [ ] Y is displayed when Z
 ```
 
 ## UIDEX_FEATURE.md files
 
-Feature docs describe a cross-cutting feature. Components are explicitly listed via frontmatter.
+Feature docs describe a cross-cutting feature that spans multiple pages. Components are explicitly listed via frontmatter.
 
-- Use `UIDEX_FEATURE.md` for features that span multiple pages (e.g., auth, billing).
+- Place feature docs in a `features/` directory inside the scanner root (e.g., `app/features/auth/UIDEX_FEATURE.md`).
+- Use one subdirectory per feature: `features/auth/`, `features/billing/`, `features/notifications/`, etc.
 - List associated component IDs in the `components:` frontmatter.
+- The description MUST be a `>` blockquote immediately after the `# Title` heading.
+- When a component participates in a cross-cutting concern (auth, billing, search, etc.) and isn't fully described by its page alone, add it to a feature.
+
+```
+features/
+  auth/
+    UIDEX_FEATURE.md
+  billing/
+    UIDEX_FEATURE.md
+```
 
 ```markdown
 ---
@@ -62,11 +124,7 @@ components:
 ---
 # Feature Name
 
-Brief description of the feature.
-
-## Acceptance
-- User can do X
-- Y is displayed when Z
+> Brief description of the feature and its scope.
 ```
 
 ## Component registry
@@ -75,14 +133,35 @@ For a project-wide view of all components, pages, and features, read the generat
 
 ## Scanner
 
-After adding, removing, or renaming `data-uidex` attributes, run:
+After adding, removing, or renaming `data-uidex`, `data-uidex-block`, or `data-uidex-primitive` attributes, run:
 
 ```bash
 npx uidex scan
 ```
 
-To validate that all components have UIDEX_PAGE.md coverage:
+To validate coverage and check for missing annotations:
 
 ```bash
-npx uidex scan --check
+npx uidex scan --audit
 ```
+
+## Setup & Administration
+
+Manage authentication, project linking, and integrations via the CLI. These commands run in the user's terminal — use `! uidex <command>` to execute them from Claude Code.
+
+```bash
+# Auth & context
+! uidex login                          # Authenticate with uidex server
+! uidex status                         # Show auth and link state
+! uidex link                           # Link current directory to org/project
+
+# Integrations
+! uidex integrations list              # List configured integrations
+! uidex integrations add jira          # Add Jira (interactive prompts)
+! uidex integrations add github        # Add GitHub (browser flow)
+! uidex integrations test <id>         # Test integration connection
+! uidex integrations remove <id>       # Remove integration (with confirmation)
+! uidex integrations targets <id>      # List available targets (repos, projects)
+```
+
+The prerequisite flow is: `login` → `link` → `integrations`. Adding/removing integrations requires org owner role.